From 481174b5664c1f504068b4779c55ebe8043e8d19 Mon Sep 17 00:00:00 2001 From: Timo Ley Date: Wed, 31 Aug 2022 14:40:32 +0200 Subject: [PATCH] API spec overhaul --- docs/SUMMARY.md | 3 ++ docs/api/README.md | 66 +++++++++---------------------------- docs/api/features/addons.md | 40 ++++++++++++++++++++++ docs/api/features/files.md | 43 +++++++++--------------- docs/concepts/namespaces.md | 6 ++-- docs/schema/api_addon.md | 39 ++++++++++++++++++++++ docs/schema/api_file.md | 34 +++++++++++++++++++ docs/schema/file.md | 6 ++-- 8 files changed, 152 insertions(+), 85 deletions(-) create mode 100644 docs/api/features/addons.md create mode 100644 docs/schema/api_addon.md create mode 100644 docs/schema/api_file.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 177a392..09aa30b 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -5,6 +5,7 @@ # API - [AddonScript API](api/README.md) + - [Addon repository](api/features/addons.md) - [File repository](api/features/files.md) # Schema @@ -16,6 +17,8 @@ - [Relation Object](schema/relation.md) - [Repository Object](schema/repository.md) - [Meta Object](schema/meta.md) +- [API Addon](schema/api_addon.md) +- [API File](schema/api_file.md) # Concepts diff --git a/docs/api/README.md b/docs/api/README.md index 0705aed..7d12eef 100755 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -6,63 +6,27 @@ The index endpoint can be used to get basic information about an API instance, including the API versions and features supported by that -instance and the default [namespace](../concepts/namespaces.md) of the instance. +instance and the [default namespace](../concepts/namespaces.md#default-namespaces) of the instance. +The response object of this endpoint contains a `versions` property, which is an object with API +version numbers as keys and the configuration objects for the specific API version as values. +For API version `v2` (AddonScript major release 2) the configuration object contains a `default_namespace` +property, which is the [default namespace](../concepts/namespaces.md#default-namespaces) of the API +instance, and a `features` property, which is an array containing all [API features](#features) +available on this API instance. #### Example response body: ``` json { - "default_namespace": "com.example", - "versions": ["v1"], - "features": ["listing", "filters", "com.example.customfeature"] + "versions": { + "v2": { + "default_namespace": "com.example", + "features": ["listing", "filters", "com.example.customfeature"] + } + } } ``` -## Basic Endpoints - -### `GET {base URL}/v1/addons/:namespace/:addon` - -This endpoint can be used to retrieve information about a specific addon, -including metadata, all available versions and the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) -of the addon. - -#### Path variales: - -- `namespace`: A [namespace](../concepts/namespaces.md) which contains the addon -- `addon`: The ID of the addon - -#### Example response body: - -``` json -{ - "id": "addon-id", - "namespace": "com.example.canonical", - "meta": { - "addon": {}, - "additional": {} - }, - "versions": [ - "1.0" - ] -} -``` - -The [meta object](../schema/meta.md) is the same as in the AddonScript files, -except, that it only includes `addon` and `additional` metadata and not `version` -specific metadata. - -### `GET {base URL}/v1/addons/:namespace/:addon/:version` - -This endpoint can be used to retrieve a specific version of an addon. -The response body of this endpoint contains the [addon schema](../schema/addon.md), -which is also used in AddonScript JSON files. - -#### Path variables: - -- `namespace`: The namespace which contains the addon -- `addon`: The ID of the addon -- `version`: The [version number](../concepts/versioning.md) of the requested version - ## Features API features can be either part of the specification itself or @@ -71,5 +35,5 @@ be in a namespace-like format (reversed domain name). These API features are part of the AddonScript specification itself: -- `files`: [File repository](./features/files.md) -- To be added \ No newline at end of file +- `addons`: [Addon repository](./features/addons.md) +- `files`: [File repository](./features/files.md) \ No newline at end of file diff --git a/docs/api/features/addons.md b/docs/api/features/addons.md new file mode 100644 index 0000000..60d97d4 --- /dev/null +++ b/docs/api/features/addons.md @@ -0,0 +1,40 @@ +# Addon repository + +## Endpoints + +### Get addon + +`GET {base URL}/v2/addons/:namespace/:addon` + +This endpoint can be used to retrieve information about a specific addon, +including metadata, all available versions and the [canonical namespace](../../concepts/namespaces.md#canonical-namespaces) +of the addon. + +#### Path variales: + +- `namespace`: A [namespace](../../concepts/namespaces.md) which contains the addon +- `addon`: The ID of the addon + +#### Responses: + +- `200 OK`: The addon is available in this addon repository. +The response body must be an [API Addon Object](../../schema/api_addon.md). +- `404 Not Found`: The addon is not available in this addon repository. + +### Get addon manifest + +`GET {base URL}/v2/addons/:namespace/:addon/:version` + +This endpoint can be used to retrieve the manifest of a specific version of an addon. + +#### Path variables: + +- `namespace`: The namespace which contains the addon +- `addon`: The ID of the addon +- `version`: The [version number](../../concepts/versioning.md) of the requested version + +#### Responses: + +- `200 OK`: This version of the addon is available in this addon repository. +The response body must be an [Addon Manifest](../../schema/addon.md). +- `404 Not Found`: This version of the addon is not available in this addon repository. \ No newline at end of file diff --git a/docs/api/features/files.md b/docs/api/features/files.md index da4433b..0065d5f 100644 --- a/docs/api/features/files.md +++ b/docs/api/features/files.md @@ -2,7 +2,9 @@ ## Endpoints -### `GET {base URL}/v1/files/:namespace/:addon/:version/:qualifier` +### Get a file by identifier + +`GET {base URL}/v2/files/:namespace/:addon/:version/:qualifier` This endpoint can be used to retrieve information about a specific file. If the instance don't know this file, it must respond with status code 404. @@ -15,22 +17,15 @@ of the addon to which the file belongs to - `version`: The addon version to which the file belongs to - `qualifier`: The qualifier of the file -#### Example response: +#### Responses: -```json -{ - "links": ["https://example.com/file.jar"], - "filename?": "file.jar", - "hashes": { - "sha1": "somesha1checksum" - }, - "meta": { - "additional": {} - } -} -``` +- `200 OK`: The file is available in this file repository. +The response body must be an [API File Object](../../schema/api_file.md). +- `404 Not Found`: The file is not available in this file repository. -### `GET {base URL}/v1/files/:algorithm/:hash` +### Get a file by hash + +`GET {base URL}/v2/files/:algorithm/:hash` This endpoint can be used to retrieve information about a file from the hash value of the file. If the instance can't find the file by the hash or does not know the specified hash algorithm, @@ -41,17 +36,9 @@ it must respond with status code 404. - `algorithm`: The hash algorithm of the hash - `hash`: The hash value of the file -#### Example response: +#### Responses: -```json -{ - "links": ["https://example.com/file.jar"], - "filename?": "file.jar", - "hashes": { - "sha1": "somesha1checksum" - }, - "meta": { - "additional": {} - } -} -``` \ No newline at end of file +- `200 OK`: The file is available in this file repository. +The response body must be an [API File Object](../../schema/api_file.md). +- `404 Not Found`: The file is either not available in this file repository +or the hash algorithm is unknown to the API instance. \ No newline at end of file diff --git a/docs/concepts/namespaces.md b/docs/concepts/namespaces.md index 3e26e85..715a8eb 100644 --- a/docs/concepts/namespaces.md +++ b/docs/concepts/namespaces.md @@ -13,14 +13,14 @@ optionally also the addon type (i.e. `com.example.repository.mods`, `com.author. While an addon can have multiple namespaces, it must have exactly one canonical namespace, which is defined in the [addon object](../schema/addon.md#namespace). -An [API instance](../api/README.md) must also return the canonical namespace of -the addon on the [addon endpoint](../api/README.md#get-base-urlv1addonsnamespaceaddon) +An [API instance](../api/) must also return the canonical namespace of +the addon on the [addon endpoint](../api/features/addons.md#get-addon) even if the addon was requested from another namespace. To check, if two addons are the same addon, thier canonical namespace and their ID must be equal. ## Default Namespaces -Each [API instance](../api/README.md) has a default namespace. Addons in the +Each [API instance](../api/) has a default namespace. Addons in the repository of that API instance should have that namespace, as long as there are no ID conflicts in the repository. The default namespace does not need to be the canonical namespace of these addons. \ No newline at end of file diff --git a/docs/schema/api_addon.md b/docs/schema/api_addon.md new file mode 100644 index 0000000..c76aeb5 --- /dev/null +++ b/docs/schema/api_addon.md @@ -0,0 +1,39 @@ +# API Addon Object + +```json +{ + "id": "myaddon", + "namespace": "com.example", + "meta": { + "addon": {}, + "additional": {} + }, + "versions": [ + "1.0" + ] +} +``` + +## Required properties + +### id + +This is the ID of the addon. + +It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces. + +### namespace + +This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the addon. + +### versions + +This is an array of all [version numbers](../concepts/versioning.md) of this addon, which are +available on this API instance. + +## Optional properties + +### meta + +This is a [meta object](meta.md) containing metadata about the addon. It does not +contain any version specific metadata. \ No newline at end of file diff --git a/docs/schema/api_file.md b/docs/schema/api_file.md new file mode 100644 index 0000000..2c4407c --- /dev/null +++ b/docs/schema/api_file.md @@ -0,0 +1,34 @@ +# API File Object + +```json +{ + "link": ["https://example.com/file.jar"], + "hashes": { + "sha1": "somesha1checksum" + }, + "meta": { + "additional": {} + } +} +``` + +## Required properties + +### link + +This is an array of [links](../concepts/links.md), which are pointing to the actual file. This must be a http(s) link. +All of these links must have the same file type. + +## Optional properties + +### hashes + +This is an object with checksums for this file. The object contains key-value-pairs where the key is the hash algorithm and the +value is the checksum. + +Supported hash algorithms: +- `sha1` + +### meta + +This is a [meta object](meta.md) containing metadata about the file. it may only contain [additional metadata](meta.md#additional). \ No newline at end of file diff --git a/docs/schema/file.md b/docs/schema/file.md index 1075ed4..dde08a2 100644 --- a/docs/schema/file.md +++ b/docs/schema/file.md @@ -27,9 +27,9 @@ This is an array of [links](../concepts/links.md), which are pointing to the act have the same file type. Since AddonScript treats directories and zip files equally, they can be mixed in the same link array. When downloading the file, the first link in this array should be used with the other links as fallback, if the first doesn't work. -If none of the specified links works, the file should be downloaded by it's Maven -specifier from one of the specified repository, but only, if a `sha1` hash is specified, so that it can be -verified, that the downloaded file is correct. +If none of the specified links works or the array is empty, the file link should be retrieved by it's identifier +from one of the [repositories](repository.md), but only, if a `sha1` hash is specified, so that it can be +verified, that the downloaded file is correct. ## Optional properties