addonscript/addonscript-spec
addonscript/addonscript-spec
1
1
Fork 2
Code Issues 3 Pull requests 1 Projects Releases 3 Wiki Activity

API spec overhaul #21

Merged
tilera merged 1 commit from tilera/addonscript-spec:repos into master 2022-08-31 14:55:38 +02:00
Conversation 0 Commits 1 Files changed 8 +152 -85
8 changed files with 152 additions and 85 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/SUMMARY.md
View file

@ -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

66
docs/api/README.md
View file

@ -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
- `addons`: [Addon repository](./features/addons.md)
- `files`: [File repository](./features/files.md)

40
docs/api/features/addons.md Normal file
View file

@ -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.

43
docs/api/features/files.md
View file

@ -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": {}
}
}
```
- `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.

6
docs/concepts/namespaces.md
View file

@ -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.

39
docs/schema/api_addon.md Normal file
View file

@ -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.

34
docs/schema/api_file.md Normal file
View file

@ -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).

6
docs/schema/file.md
View file

@ -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