Repository API » History » Version 14
koszko, 12/06/2021 08:03 PM
rethink the design of Hydrilla
| 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 | "payloads": [ |
||
| 131 | { |
||
| 132 | 8 | koszko | "pattern": "https://example.org/a/*", |
| 133 | 9 | koszko | "payload": "some-KISS-resource" |
| 134 | }, { |
||
| 135 | 4 | koszko | "pattern": "https://example.org/t/*", |
| 136 | "payload": "another-KISS-resource" |
||
| 137 | 1 | jahoti | } |
| 138 | ] |
||
| 139 | } |
||
| 140 | ``` |
||
| 141 | 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". |
| 142 | 12 | koszko | |
| 143 | ### Querying patterns that match given url |
||
| 144 | 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: |
| 145 | 12 | koszko | ``` javascript |
| 146 | 14 | koszko | { |
| 147 | "api_schema_version": [1], |
||
| 148 | "api_schema_revision": 1, |
||
| 149 | "mappings": [ |
||
| 150 | { |
||
| 151 | "identifier": "example-org-minimal", |
||
| 152 | "version": [2022, 5, 10] |
||
| 153 | }, |
||
| 154 | "identifier": "example-org-experimantal", |
||
| 155 | "version": [0, 4] |
||
| 156 | } |
||
| 157 | ] |
||
| 158 | 12 | koszko | }] |
| 159 | ``` |
||
| 160 | |||
| 161 | 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. |
| 162 | 12 | koszko | |
| 163 | ### Fetching source info |
||
| 164 | 14 | koszko | By "source" we mean description of a source package used to build Hydrilla site content. |
| 165 | 12 | koszko | |
| 166 | 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: |
| 167 | 12 | koszko | ``` javascript |
| 168 | { |
||
| 169 | 14 | koszko | "api_schema_version": [1], |
| 170 | "api_schema_revision": 1, |
||
| 171 | "source_name": "hello", |
||
| 172 | "source_copyright": [ |
||
| 173 | { |
||
| 174 | "file": "report.spdx", |
||
| 175 | "sha256": "d5f6e58c5d55cdea7872f3f672d3b68d6c364ee8cb7cb2af0efe7d50c7d40dc5" |
||
| 176 | }, { |
||
| 177 | "file": "LICENSES/CC0-1.0.txt", |
||
| 178 | "sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499" |
||
| 179 | } |
||
| 180 | 12 | koszko | ], |
| 181 | 14 | koszko | "source_archives": [{ |
| 182 | "extension": "zip", |
||
| 183 | "sha256": "688461da362ffe2fc8e85db73e709a5356d41c8aeb7d1eee7170c64ee21dd2a2" |
||
| 184 | }] |
||
| 185 | 12 | koszko | "upstream_url": "https://git.koszko.org/pydrilla/tree/src/test/example_content/hello", |
| 186 | "definitions": [ |
||
| 187 | { |
||
| 188 | "type": "resource", |
||
| 189 | "identifier": "helloapple", |
||
| 190 | "version": [2021, 11, 10], |
||
| 191 | }, { |
||
| 192 | "type": "resource", |
||
| 193 | "identifier": "hello-message", |
||
| 194 | "version": [2021, 11, 10], |
||
| 195 | }, { |
||
| 196 | "type": "mapping", |
||
| 197 | "identifier": "helloapple", |
||
| 198 | "version": [2021, 11, 10], |
||
| 199 | } |
||
| 200 | ] |
||
| 201 | 9 | koszko | } |
| 202 | 1 | jahoti | ``` |
| 203 | |||
| 204 | 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`. |
| 205 | |||
| 206 | With api_schema_version beginning with major number 1, zip archive is always guaranteed to be available. |