Project

General

Profile

Repository API » History » Version 11

koszko, 11/19/2021 10:09 AM
minor corrections

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
Also, once we get to do the redesign discussed in the <https://hydrillabugs.koszko.org/boards/1/topics/56>, the JSON will look more like the following.
65
66 5 koszko
*(note: this API schema somewhat resembles the [[Hydrilla on-disk data format]])*
67
68 4 koszko
### Fetching resource info
69
"resource" is now the equivalent of what we used to call "bag".
70
71 9 koszko
`hydrilla.example.com/resources/helloapple` returns:
72 4 koszko
``` javascript
73 1 jahoti
{
74 9 koszko
    "source_name": "hello",
75
    "source_copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
76
    "source_licenses": "CC0-1.0",
77 1 jahoti
    "type": "resource",
78 5 koszko
    "identifier": "helloapple",
79
    "long_name": "Hello Apple",
80 4 koszko
    "uuid": "a6754dcb-58d8-4b7a-a245-24fd7ad4cd68",
81 7 koszko
    "version": [2021, 11, 10],
82
    "revision": 1,
83 4 koszko
    "description": "greets an apple",
84
    "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
85
    "licenses": "CC0-1.0",
86
    "dependencies": ["hello-message"],
87
    "scripts": [
88
	{
89 10 koszko
	    "file": "hello.js",
90 4 koszko
	    "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
91
	    "licenses":  ["CC0-1.0", "or", "GPL-3.0-or-later"],
92
	    "sha256": "04d9c4e50c1ce40f9b7b7699a9202f23eaee31069e288502284dbbea7a38e468"
93
	}, {
94 10 koszko
	    "file": "bye.js",
95 4 koszko
	    "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
96
	    "licenses":  "CC0-1.0",
97
	    "sha256": "92ae552d06ef22b48cef926861b6adec522ea08906e3dc5ae2705c1175b8fc48"
98
	}
99 1 jahoti
    ]
100
}
101
```
102
103 9 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 specifying a "ver" parameter to GET request (e.g. by appending `?ver=2021.11.2-2` to the URL). Alternatively, a JSON list of all versions of a resource definition can be obtained by specifying "?ver=all". "hello.js" can then be retrieved by issuing GET request to `hydrilla.example.com/sources/hello/hello.js`.
104 4 koszko
105 1 jahoti
### Fetching mapping info
106
"mapping" is now a set of what we used to call "pattern".
107 4 koszko
108 9 koszko
`hydrilla.example.com/mappings/example-org-minimal` returns:
109 1 jahoti
``` javascript
110
{
111 9 koszko
    "source_name": "example-org-fixes-new",
112
    "source_copyright": [{"years": ["2021-2022"], "holder": "John Smith"}],
113
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
114 1 jahoti
    "type": "mapping",
115
    "identifier": "example-org-minimal",
116 4 koszko
    "long_name": "Example.org Minimal",
117
    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
118 9 koszko
    "version": [2022, 5, 10],
119 1 jahoti
    "description": "suckless something something",
120 8 koszko
    "payloads": [
121 1 jahoti
	{
122 4 koszko
            "pattern":  "https://example.org/a/*",
123 1 jahoti
            "payload":  "some-KISS-resource"
124 4 koszko
        }, {
125
            "pattern":  "https://example.org/t/*",
126 1 jahoti
            "payload":  "another-KISS-resource"
127 4 koszko
        }
128 1 jahoti
    ]
129
}
130
```
131 9 koszko
or 404 Not Found in case "example-org-minimal" resource does not exist. If multiple versions are available, newest version's JSON description gets returned. A different one can be retrieved by specifying a "ver" parameter to GET request (e.g. by appending `?ver=2021.11.2-2` to the URL). Alternatively, a JSON list of all versions of a mapping definition can be obtained by specifying "?ver=all".
132 1 jahoti
133 9 koszko
### Fetching license info
134
`hydrilla.example.com/licenses/GPL-3.0-only` returns:
135
``` javascript
136
{
137
    "source_name": "common-licenses",
138
    "source_copyright": [{"years": ["2021"], "holder": "Hydrilla developers"}],
139
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
140
    "type": "license",
141
    "identifier": "GPL-3.0-only",
142
    "long_name": "GNU General Public License v3.0 only",
143
    "revision": 2,
144
    "legal_text": [{
145
            "format": "text/plain",
146
            "file":   "gpl-3.0.txt"
147
        }, {
148
            "format": "text/html",
149
            "file":   "gpl-3.0.html"
150
        }],
151 11 koszko
    "notice": {
152
        "file": "gpl-3.0-notice.txt"
153
    }
154 9 koszko
}
155
```
156
or 404 Not Found in case "GPL-3.0-only" license does not exist. License text can then be retrieved by issuing GET request to `hydrilla.example.com/sources/common-licenses/gpl-3.0.txt`. Notice used with the license (if applicable, as in the case of the GPL) can be retrieved from `hydrilla.example.com/sources/common-licenses/gpl-3.0-notice.txt`.
157
158 1 jahoti
### Querying patterns that match given url
159
160 9 koszko
`hydrilla.example.com/query?url=https://example.org/a/b` returns:
161 1 jahoti
``` javascript
162
[{
163 9 koszko
    "source_name": "example-org-fixes-new",
164
    "source_copyright": [{"years": ["2021-2022"], "holder": "John Smith"}],
165
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
166 1 jahoti
    "type": "mapping",
167 4 koszko
    "identifier": "example_org_minimal",
168
    "long_name": "Example.org Minimal",
169
    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
170 7 koszko
    "version": [2021, 11, 10],
171 1 jahoti
    "description": "suckless something something",
172 8 koszko
    "payloads": [{
173 1 jahoti
            "pattern":  "https://example.org/a/*",
174
            "payload":  "some-KISS-resource"
175
        }, {
176
            "pattern":  "https://example.org/t/*",
177
            "payload":  "another-KISS-resource"
178
        }]
179
}, {
180 9 koszko
    "source_name": "example-org-fixes-new",
181
    "source_copyright": [{
182
            "years": ["2021"],
183
            "holder": "JavaScript Hooky-Gooky Inc."
184
        }, {
185
            "years": ["2021"],
186
            "holder": "Abdul Ihn Ah-Ersh"
187
        }],
188
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
189 4 koszko
    "type": "mapping",
190
    "identifier": "example_org_experimantal",
191
    "long_name": "Example.org Experimantal"
192
    "uuid": "edc86a6a-2911-422f-901f-08edc00391b4",
193 7 koszko
    "version": [0, 4],
194 4 koszko
    "description": "[...]; patches are WANTED!",
195 8 koszko
    "payloads": [{
196 1 jahoti
            "pattern":  "https://example.org/**",
197
            "payload":  "quick-and-dirty-resource"
198
        }]
199
}]
200
```
201
202
or `[]` in case no mappings match that URL. In case many versions of some mapping match the URL, only the most current of those versions that do is included. In case the URL is of wrong format, 400 Bad Request is returned.
203 9 koszko
204
### Fetching source info
205
By "source" we mean contents of an index.json file from which item definitions come.
206
207
`hydrilla.example.com/sources/hello` returns:
208
``` javascript
209
{
210
    "schema_version": [0, 2],
211
    "schema_revision": 1,
212
    "copyright":  [
213
	{
214
	    "years": ["2021"],
215
	    "holder": "Wojtek Kosior"
216
	}
217
    ],
218
    "licenses": "CC0-1.0",
219
    "upstream_url": "https://git.koszko.org/pydrilla/tree/example_content/hello",
220
    "package_url": "https://git.koszko.org/pydrilla/tree/example_content/hello",
221
    "definitions": [
222
	{
223
	    "type": "resource",
224
	    "identifier": "helloapple",
225
	    "long_name": "Hello Apple",
226
	    "uuid": "a6754dcb-58d8-4b7a-a245-24fd7ad4cd68",
227
	    "version": [2021, 11, 10],
228
	    "revision": 1,
229
	    "description": "greets an apple",
230
	    "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
231
	    "licenses": "CC0-1.0",
232
	    "dependencies": ["hello-message"],
233
	    "scripts": [
234
		{
235 10 koszko
		    "file": "hello.js",
236 9 koszko
		    "copyright": "auto",
237
		    "licenses":  "auto"
238
		}, {
239 10 koszko
		    "file":   "bye.js"
240 9 koszko
		}
241
	    ]
242
	}, {
243
	    "type":       "resource",
244
	    "identifier": "hello-message",
245
	    "long_name":  "Hello Message",
246
	    "uuid":       "1ec36229-298c-4b35-8105-c4f2e1b9811e",
247
	    "version":     [2021, 11, 10],
248
	    "revision":    2,
249
	    "description": "define messages for saying hello and bye",
250
	    "copyright":   [{"years": ["2021"], "holder": "Wojtek Kosior"}],
251
	    "licenses":    "CC0-1.0",
252 10 koszko
	    "scripts": [{"file": "message.js"}]
253 9 koszko
	}, {
254
	    "type": "mapping",
255
	    "identifier": "helloapple",
256
	    "long_name": "Hello Apple",
257
	    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
258
	    "version": [2021, 11, 10],
259
	    "description": "causes apple to get greeted on Hydrillabugs issue tracker",
260
	    "payloads": [
261
		{
262
		    "pattern": "https://hydrillabugs.koszko.org/***",
263
		    "payload": "helloapple"
264
		},
265
		{
266
		    "pattern": "https://hachettebugs.koszko.org/***",
267
		    "payload": "helloapple"
268
		}
269
	    ]
270
	}, {
271
	    "type": "license",
272
	    "identifier": "CC0-1.0",
273
	    "long_name": "Creative Commons Zero v1.0 Universal",
274
            "revision": 1,
275
	    "legal_text": [
276
		{
277
		    "format": "text/plain",
278
		    "file":   "cc0.txt"
279
		}
280
	    ]
281
	}
282
    ]
283
}
284
```
285
286
Alternatively, "/index.json" can be appended to the URL to obtain the original index.json, possibly with "//" comments and values like "auto" in some fields.