Project

General

Profile

Actions

Repository API » History » Revision 13

« Previous | Revision 13/25 (diff) | Next »
koszko, 11/19/2021 11:22 AM
minor corrections


Repository API

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/resources/helloapple returns:

{
    "source_name": "hello",
    "source_copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
    "source_licenses": "CC0-1.0",
    "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": [
        {
            "file": "hello.js",
            "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
            "licenses":  ["CC0-1.0", "or", "GPL-3.0-or-later"],
            "sha256": "04d9c4e50c1ce40f9b7b7699a9202f23eaee31069e288502284dbbea7a38e468"
        }, {
            "file": "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. 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.

Fetching mapping info

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

hydrilla.example.com/mappings/example-org-minimal returns:

{
    "source_name": "example-org-fixes-new",
    "source_copyright": [{"years": ["2021-2022"], "holder": "John Smith"}],
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
    "type": "mapping",
    "identifier": "example-org-minimal",
    "long_name": "Example.org Minimal",
    "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
    "version": [2022, 5, 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. 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".

Fetching license info

hydrilla.example.com/licenses/GPL-3.0-only returns:

{
    "source_name": "common-licenses",
    "source_copyright": [{"years": ["2021"], "holder": "Hydrilla developers"}],
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
    "type": "license",
    "identifier": "GPL-3.0-only",
    "long_name": "GNU General Public License v3.0 only",
    "revision": 2,
    "legal_text": [{
            "format": "text/plain",
            "file":   "gpl-3.0.txt",
            "sha256": "3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
        }, {
            "format": "text/html",
            "file":   "gpl-3.0.html",
            "sha256": "f20948605b5d8e349977579aae01357e50f9fe4d158fc044d33c35b5fab41684"
        }],
    "notice": {
        "file":   "gpl-3.0-notice.txt",
        "sha256": "46085ca5f53d3f7818c452c9efc6850af4c38075ad4da44eb51fd97d9e84d970"
    }
}

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.

Querying patterns that match given url

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

[{
    "source_name": "example-org-fixes-new",
    "source_copyright": [{"years": ["2021-2022"], "holder": "John Smith"}],
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
    "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"
        }]
}, {
    "source_name": "example-org-fixes-new",
    "source_copyright": [{
            "years": ["2021"],
            "holder": "JavaScript Hooky-Gooky Inc."
        }, {
            "years": ["2021"],
            "holder": "Abdul Ihn Ah-Ersh"
        }],
    "source_licenses": ["Apache-2.0", "and", "CC-BY-SA-4.0"],
    "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.

Fetching source info

By "source" we mean contents of an index.json file from which item definitions come.

hydrilla.example.com/sources/hello/index.json could return something like:

// SPDX-License-Identifier: CC0-1.0

// Copyright (C) 2021 Wojtek Kosior
// Available under the terms of Creative Commons Zero v1.0 Universal.

{
    "schema_version": [0, 2],
    "schema_revision": 1,
    "copyright":  [
        {
            "years": ["2021"],
            "holder": "Wojtek Kosior"
        }
    ],
    "licenses": "CC0-1.0",
    "upstream_url": "https://git.koszko.org/pydrilla/tree/src/test/example_content/hello",
    "package_url": "https://git.koszko.org/pydrilla/tree/src/test/example_content/hello",
    "definitions": [
        {
            "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": [
                {
                    "file": "hello.js",
                    "copyright": "auto",
                    "licenses":  "auto"
                }, {
                    "file":   "bye.js"
                }
            ]
        }, {
            "type":       "resource",
            "identifier": "hello-message",
            "long_name":  "Hello Message",
            "uuid":       "1ec36229-298c-4b35-8105-c4f2e1b9811e",
            "version":     [2021, 11, 10],
            "revision":    2,
            "description": "define messages for saying hello and bye",
            "copyright":   [{"years": ["2021"], "holder": "Wojtek Kosior"}],
            "licenses":    "CC0-1.0",
            "scripts": [{"file": "message.js"}]
        }, {
            "type": "mapping",
            "identifier": "helloapple",
            "long_name": "Hello Apple",
            "uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
            "version": [2021, 11, 10],
            "description": "causes apple to get greeted on Hydrillabugs issue tracker",
            "payloads": [
                {
                    "pattern": "https://hydrillabugs.koszko.org/***",
                    "payload": "helloapple"
                },
                {
                    "pattern": "https://hachettebugs.koszko.org/***",
                    "payload": "helloapple"
                }
            ]
        }, {
            "type": "license",
            "identifier": "CC0-1.0",
            "long_name": "Creative Commons Zero v1.0 Universal",
            "revision": 2,
            "legal_text": [
                {
                    "format": "text/plain",
                    "file":   "cc0.txt"
                }
            ]
        }
    ]
}

Returned are the contents of index.json that Hydrilla processes to construct other definitions. "//" comments are allowed to appear there as an extension to JSON. For details about this file's structure, see here.

Updated by koszko almost 2 years ago · 13 revisions

Also available in: PDF HTML TXT