Repository API¶

• Table of contents
• Repository API
  • Under current schema
    • Fetching script info
    • Fetching bag info
    • Fetching pattern info
    • Querying patterns that match given URL
  • Under the upcoming schema
    • Fetching resource info
    • Fetching mapping info
    • Querying patterns that match given url

Under current schema¶

Fetching script info¶

hydrilla.example.com/script?n=helloscript returns:

{
    "name": "helloscript",
    "location": "somedirectory/hello.js",
    "sha256":   "e4dbe4dba40e8bd159fb987b0f0cf2c243d7e6b9b9dc792e58dedf1fae38b0a1"
}

or 404 Not Found in case "helloscript" script does not exist. hydrilla.example.com/content/somedirectory/hello.js holds the actual script source.

Fetching bag info¶

hydrilla.example.com/bag?n=hellobag returns:

{
    "name": "hellobag",
    "components":   [["s", "helloscript"], ["s", "someotherscript"], ["b", "somebag"]]
}

or 404 Not Found in case "hellobag" bag does not exist.

Fetching pattern info¶

hydrilla.example.com/pattern?n=https://example.org/a/* returns:

{
    "pattern":  "https://example.org/a/*",
    "payload":  ["b", "hellobag"]
}

or 404 Not Found in case requested pattern does not exist.

Querying patterns that match given URL¶

Finally, hydrilla.example.com/query?n=https://example.org/a/b returns:

[{
        "pattern":  "https://example.org/a/*",
        "payload":  ["b", "hellobag"]
    }, {
        "pattern":  "https://example.org/a/b",
        "payload":  ["b", "fix_by_mrcooldev"]
    }, {
        "pattern":  "https://example.org/a/b",
        "payload":  ["b", "mod_by_missgreatskill"]
    }]

or in case no patterns match the requested URL, it returns just:

[]

or in case the URL is of wrong format it returns some HTTP error.

Under the upcoming schema¶

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.

(note: this API schema somewhat resembles the Hydrilla on-disk data format)

Fetching resource info¶

"resource" is now the equivalent of what we used to call "bag".

hydrilla.example.com/resource?n=helloapple returns:

{
    "type": "resource",
    "identifier": "helloapple",
    "long_name": "Hello Apple",
    "uuid": "a6754dcb-58d8-4b7a-a245-24fd7ad4cd68",
    "version": [2021, 11, 10],
    "revision": 1,
    "description": "greets an apple",
    "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
    "licenses": "CC0-1.0",
    "dependencies": ["hello-message"],
    "scripts": [
    {
        "name": "hello.js",
        "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
        "licenses":  ["CC0-1.0", "or", "GPL-3.0-or-later"],
        "sha256": "04d9c4e50c1ce40f9b7b7699a9202f23eaee31069e288502284dbbea7a38e468"
    }, {
        "name": "bye.js",
        "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
        "licenses":  "CC0-1.0",
        "sha256": "92ae552d06ef22b48cef926861b6adec522ea08906e3dc5ae2705c1175b8fc48"
    }
    ]
}

or 404 Not Found in case resource "helloapple" does not exists. If multiple versions are available, newest version's JSON description gets returned. Another one can be retrieved by specifying a "ver" parameter to GET request (e.g. by appending &ver=2021.11.2-2 to the URL).

Fetching mapping info¶

"mapping" is now a set of what we used to call "pattern".

hydrilla.example.com/mapping?n=example-org-minimal returns:

{
    "type": "mapping",
    "identifier": "example-org-minimal",
    "long_name": "Example.org Minimal",
    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
    "version": [2021, 11, 10],
    "description": "suckless something something",
    "payloads": [
    {
            "pattern":  "https://example.org/a/*",
            "payload":  "some-KISS-resource"
        }, {
            "pattern":  "https://example.org/t/*",
            "payload":  "another-KISS-resource"
        }
    ]
}

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. Another one can be retrieved by specifying a "ver" parameter to GET request (e.g. by appending &ver=2021.11.2-2 to the URL).

Querying patterns that match given url¶

hydrilla.example.com/query?n=https://example.org/a/b returns:

[{
    "type": "mapping",
    "identifier": "example_org_minimal",
    "long_name": "Example.org Minimal",
    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
    "version": [2021, 11, 10],
    "description": "suckless something something",
    "payloads": [{
            "pattern":  "https://example.org/a/*",
            "payload":  "some-KISS-resource"
        }, {
            "pattern":  "https://example.org/t/*",
            "payload":  "another-KISS-resource"
        }]
}, {
    "type": "mapping",
    "identifier": "example_org_experimantal",
    "long_name": "Example.org Experimantal"
    "uuid": "edc86a6a-2911-422f-901f-08edc00391b4",
    "version": [0, 4],
    "description": "[...]; patches are WANTED!",
    "payloads": [{
            "pattern":  "https://example.org/**",
            "payload":  "quick-and-dirty-resource"
        }]
}]

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.