Project

General

Profile

Repository API » History » Version 18

koszko, 01/19/2022 09:35 AM
also include mappings' long names in query results

1 1 jahoti
# Repository API
2
3
{{toc}}
4
5
## Under current schema
6
7
### Fetching script info
8
9
`hydrilla.example.com/script?n=helloscript` returns:
10 4 koszko
``` javascript
11 1 jahoti
{
12
    "name": "helloscript",
13
    "location": "somedirectory/hello.js",
14
    "sha256":   "e4dbe4dba40e8bd159fb987b0f0cf2c243d7e6b9b9dc792e58dedf1fae38b0a1"
15
}
16
```
17 2 jahoti
or 404 Not Found in case "helloscript" script does not exist. `hydrilla.example.com/content/somedirectory/hello.js` holds the actual script source.
18 1 jahoti
19
### Fetching bag info
20
21
`hydrilla.example.com/bag?n=hellobag` returns:
22 4 koszko
``` javascript
23 1 jahoti
{
24
    "name": "hellobag",
25
    "components":   [["s", "helloscript"], ["s", "someotherscript"], ["b", "somebag"]]
26
}
27
```
28
or 404 Not Found in case "hellobag" bag does not exist.
29
30
### Fetching pattern info
31
32
`hydrilla.example.com/pattern?n=https://example.org/a/*` returns:
33 4 koszko
``` javascript
34 1 jahoti
{
35
    "pattern":  "https://example.org/a/*",
36
    "payload":  ["b", "hellobag"]
37
}
38
```
39
or 404 Not Found in case requested pattern does not exist.
40
41
### Querying patterns that match given URL
42
43
Finally, `hydrilla.example.com/query?n=https://example.org/a/b` returns:
44 4 koszko
``` javascript
45 1 jahoti
[{
46
        "pattern":  "https://example.org/a/*",
47
        "payload":  ["b", "hellobag"]
48
    }, {
49
        "pattern":  "https://example.org/a/b",
50
        "payload":  ["b", "fix_by_mrcooldev"]
51
    }, {
52
        "pattern":  "https://example.org/a/b",
53
        "payload":  ["b", "mod_by_missgreatskill"]
54
    }]
55
```
56
or in case no patterns match the requested URL, it returns just:
57 4 koszko
``` javascript
58 1 jahoti
[]
59
```
60
or in case the URL is of wrong format it returns some HTTP error.
61
62
## Under the upcoming schema
63
64 14 koszko
Also, once we get to do the redesign discussed in [this forum thread](/boards/1/topics/56), current interface will be replaced with the following.
65 5 koszko
66 1 jahoti
### Fetching resource info
67 4 koszko
"resource" is now the equivalent of what we used to call "bag".
68 1 jahoti
69 14 koszko
Let's assume we want to retrieve the definition of resource `helloapple`. We can issue a GET to `hydrilla.example.com/resources/helloapple.json`. It returns:
70 4 koszko
``` javascript
71 1 jahoti
{
72 14 koszko
    "api_schema_version": [1],
73
    "api_schema_revision": 1,
74 1 jahoti
    "source_name": "hello",
75 14 koszko
    "source_copyright": [
76
	{
77
	    "file": "report.spdx",
78
	    "sha256": "d5f6e58c5d55cdea7872f3f672d3b68d6c364ee8cb7cb2af0efe7d50c7d40dc5"
79
	}, {
80
	    "file": "LICENSES/CC0-1.0.txt",
81
	    "sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499"
82
	}
83
    ],
84 7 koszko
    "type": "resource",
85 4 koszko
    "identifier": "helloapple",
86
    "long_name": "Hello Apple",
87
    "uuid": "a6754dcb-58d8-4b7a-a245-24fd7ad4cd68",
88
    "version": [2021, 11, 10],
89 12 koszko
    "revision": 1,
90
    "description": "greets an apple",
91 1 jahoti
    "dependencies": ["hello-message"],
92 12 koszko
    "scripts": [
93
        {
94
            "file": "hello.js",
95 1 jahoti
            "sha256": "04d9c4e50c1ce40f9b7b7699a9202f23eaee31069e288502284dbbea7a38e468"
96 12 koszko
        }, {
97
            "file": "bye.js",
98 1 jahoti
            "sha256": "92ae552d06ef22b48cef926861b6adec522ea08906e3dc5ae2705c1175b8fc48"
99
        }
100
    ]
101
}
102
```
103
104 14 koszko
or 404 Not Found in case resource "helloapple" does not exists. If multiple versions are available, newest version's JSON description gets returned. A different one can be retrieved by including version in the GET request. Requested path should then take the form `/resources/<resource_name>/<version>.json` (e.g. `GET hydrilla.example.com/resources/helloapple/2021.11.10.json`). Alternatively, a JSON list of all versions of a resource definition can be obtained by specifying `?ver=all` (e.g. `GET hydrilla.example.com/resources/helloapple.json?ver=all`). File can be retrieved by issuing a GET request to `hydrilla.example.com/files/sha256-<file's_sha256_sum>`. For example, requests to `hydrilla.example.com/files/a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499` and `hydrilla.example.com/files/04d9c4e50c1ce40f9b7b7699a9202f23eaee31069e288502284dbbea7a38e468` yield contents of "LICENSES/CC0-1.0.txt" and "hello.js", respectively.
105 1 jahoti
106
### Fetching mapping info
107
"mapping" is now a set of what we used to call "pattern".
108
109 14 koszko
Let's assume we want to retrieve the definition of mapping `example-org-minimal`. We can issue a GET to `hydrilla.example.com/mappings/example-org-minimal.json`. It returns:
110 1 jahoti
``` javascript
111
{
112 14 koszko
    "api_schema_version": [1],
113
    "api_schema_revision": 1,
114 1 jahoti
    "source_name": "example-org-fixes-new",
115 14 koszko
    "source_copyright": [
116
	{
117
	    "file": "report.spdx",
118
	    "sha256": "d5f6e58c5d55cdea7872f3f672d3b68d6c364ee8cb7cb2af0efe7d50c7d40dc5"
119
	}, {
120
	    "file": "LICENSES/CC0-1.0.txt",
121
	    "sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499"
122
	}
123
    ],
124 1 jahoti
    "type": "mapping",
125 9 koszko
    "identifier": "example-org-minimal",
126 1 jahoti
    "long_name": "Example.org Minimal",
127 9 koszko
    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
128 1 jahoti
    "version": [2022, 5, 10],
129 4 koszko
    "description": "suckless something something",
130 15 koszko
    "payloads": {
131
        "https://example.org/a/*": {
132
            "identifier": "some-KISS-resource"
133
        },
134
        "https://example.org/t/*": {
135
            "identifier":  "another-KISS-resource"
136 1 jahoti
        }
137 15 koszko
    }
138 1 jahoti
}
139
```
140 14 koszko
or 404 Not Found in case "example-org-minimal" mapping does not exist. If multiple versions are available, newest version's JSON description gets returned. A different one can be retrieved by including version in the GET request. Requested path should then take the form `/mappings/<mapping_name>/<version>.json` (e.g. `GET hydrilla.example.com/mappings/example-org-minimal/2022.5.10.json`). Alternatively, a JSON list of all versions of a mapping definition can be obtained by specifying `?ver=all` (e.g. `GET hydrilla.example.com/mappings/example-org-minimal.json?ver=all`). File can be retrieved by issuing a GET request to `hydrilla.example.com/files/sha256-<file's_sha256_sum>`. For example, request to `hydrilla.example.com/files/a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499` yields contents of "LICENSES/CC0-1.0.txt".
141 12 koszko
142 17 koszko
### Querying mappings that match given URL
143 14 koszko
Assume we want to query mappings with patterns matching `https://example.org/a/b`. We can issue a GET to `hydrilla.example.com/query?url=https://example.org/a/b`. It returns:
144 12 koszko
``` javascript
145 1 jahoti
{
146 14 koszko
    "api_schema_version": [1],
147
    "api_schema_revision": 1,
148
    "mappings": [
149
        {
150
            "identifier": "example-org-minimal",
151 18 koszko
            "long_name": "Example.org Minimal",
152 16 koszko
            "version": [2022, 5, 10]
153
        },
154
            "identifier": "example-org-experimental",
155 18 koszko
            "long_name": "example.org fix bundle",
156 16 koszko
            "version": [0, 4]
157
        }
158 14 koszko
    ]
159 12 koszko
}]
160
```
161
162 14 koszko
The value of "mappings" can be an empty array (`[]`) in case no mappings match given URL. In case many versions of some mapping match the URL, only the most current of those versions that do is listed. In case the URL is of wrong format, 400 Bad Request is returned.
163 12 koszko
164
### Fetching source info
165 14 koszko
By "source" we mean description of a source package used to build Hydrilla site content.
166 12 koszko
167 14 koszko
Assume we want to get description of source package `hello`. We can issue a GET to `hydrilla.example.com/sources/hello.json`. It returns:
168 12 koszko
``` javascript
169
{
170 14 koszko
    "api_schema_version": [1],
171
    "api_schema_revision": 1,
172
    "source_name": "hello",
173
    "source_copyright": [
174
	{
175
	    "file": "report.spdx",
176
	    "sha256": "d5f6e58c5d55cdea7872f3f672d3b68d6c364ee8cb7cb2af0efe7d50c7d40dc5"
177
	}, {
178
	    "file": "LICENSES/CC0-1.0.txt",
179
	    "sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499"
180
	}
181 12 koszko
    ],
182 14 koszko
    "source_archives": [{
183
	"extension": "zip",
184
	"sha256": "688461da362ffe2fc8e85db73e709a5356d41c8aeb7d1eee7170c64ee21dd2a2"
185
    }]
186 12 koszko
    "upstream_url": "https://git.koszko.org/pydrilla/tree/src/test/example_content/hello",
187
    "definitions": [
188
        {
189
            "type": "resource",
190
            "identifier": "helloapple",
191
            "version": [2021, 11, 10],
192
        }, {
193
            "type":       "resource",
194
            "identifier": "hello-message",
195
            "version":     [2021, 11, 10],
196
        }, {
197
            "type": "mapping",
198
            "identifier": "helloapple",
199
            "version": [2021, 11, 10],
200
        }
201
    ]
202 9 koszko
}
203 1 jahoti
```
204
205 14 koszko
Or 404 Not Found in case no such source package exists. Here "zip" was listed among available source archive extensions. It means we can download the zip archive of this source package by issuing GET to `hydrilla.example.com/sources/hello.zip`.
206
207
With api_schema_version beginning with major number 1, zip archive is always guaranteed to be available.