forked from addonscript/addonscript-spec
API spec overhaul
This commit is contained in:
parent
f14ec070d4
commit
481174b566
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue