Basic API specification

This commit is contained in:
Timo Ley 2022-02-25 22:54:10 +01:00
parent 881fb1044b
commit b0d25a7018
2 changed files with 78 additions and 0 deletions

View file

@ -2,6 +2,10 @@
- [AddonScript](README.md) - [AddonScript](README.md)
# API
- [API](api/README.md)
# Schema # Schema
- [Addon Object](schema/addon.md) - [Addon Object](schema/addon.md)

74
docs/api/README.md Executable file
View file

@ -0,0 +1,74 @@
# The AddonScript API
## The Index Endpoint
### `GET {base URL}`
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 of the instance.
#### Example response body:
``` json
{
"default_namespace": "com.example",
"versions": ["v1"],
"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 of
the addon.
#### Path variales:
- `namespace`: The namespace 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,
exept, 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
are specified by third parties. Third-party API features should
be in a namespace-like format (reversed domain name).
These API features are part of the AddonScript specification itself:
- To be added