Namespace and repository overhaul

This commit is contained in:
Timo Ley 2022-09-23 18:33:14 +02:00
parent 041fad3e6f
commit 27ad758268
6 changed files with 53 additions and 33 deletions

View file

@ -9,10 +9,8 @@ instance, including the API versions and features supported by that
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.
For API version `v2` (AddonScript major release 2) the configuration object contains a `features`
property, which is an array containing all [API features](#features) available on this API instance.
### Example response body:
@ -20,8 +18,7 @@ available on this API instance.
{
"versions": {
"v2": {
"default_namespace": "com.example",
"features": ["listing", "filters", "com.example.customfeature"]
"features": ["addons", "env", "com.example.customfeature"]
}
}
}

View file

@ -12,7 +12,7 @@ of the addon.
#### Path variales:
- `namespace`: A [namespace](../../concepts/namespaces.md) which contains the addon
- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
- `addon`: The ID of the addon
#### Responses:
@ -29,7 +29,7 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
#### Path variables:
- `namespace`: The namespace which contains the addon
- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
- `addon`: The ID of the addon
- `version`: The [version number](../../concepts/versioning.md) of the requested version
@ -38,3 +38,14 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
- `200 OK`: This version of the addon is available in this addon repository.
The response body MUST be an [Addon Manifest](../../schema/manifest.md).
- `404 Not Found`: This version of the addon is not available in this addon repository.
### Get namespaces
`GET {base URL}/v2/namespaces`
This endpoint can be used to get a list of [repository namespaces](../../concepts/namespaces.md#repository-namespaces),
which can be found on this API instance. It MAY be incomplete or empty at all.
#### Responses:
- `200 OK`: The response body MUST be a JSON array of namespace strings.

View file

@ -1,6 +1,7 @@
# Namespaces
Namespaces are used in conjunction with addon IDs to uniquely identify an addon.
Namespaces are used in conjunction with addon IDs to uniquely identify an addon as well as
an identifier for repositories.
## Format
@ -9,18 +10,24 @@ They SHOULD be in a reversed domain name format. A namespace SHOULD specify the
(i.e. `com.example.repository`) or the author (i.e. `com.author.website`) of the addon and
optionally also the addon type (i.e. `com.example.repository.mods`, `com.author.website.modpacks`).
## Repository Namespaces
A repository namespace describes an addon repository across [API instances](../api/). A repository
contains different addons and MAY be hosted on multiple API instances (mirrors). The ID of an addon
MUST be unique in a repository, so an addon can be resolved by the addon ID in conjuction with the
repository namespace. Since the same addon MAY be contained in multiple repositories, it MUST have a
[canonical namespace](#canonical-namespaces), so it can be identified globally. The repository
described by the canonical namespace of an addon MUST also contain that addon. If different API
instances return contradicting information about a repository, for example an addon with the same
ID in the same repository has different canonical namespaces on different instances, the AddonScript
implementation decides, which instance is more trustworthy. This MAY be done by comparing the
repository namespace to the API URL or by asking the user.
## Canonical Namespaces
While an addon MAY have multiple namespaces, it MUST have exactly one canonical
namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace).
While an addon MAY be included in multiple repository namespaces, it MUST have exactly
one canonical namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace).
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
even if the addon was requested from another repository namespace. To check, if two addons
are the same addon, their canonical namespace and their ID MUST be equal.
## Default Namespaces
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.

View file

@ -52,7 +52,8 @@ This is an array of [relation objects](relation.md) which represent addons in re
### repositories
This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or
addons can be retrieved.
addons can be retrieved. Each AddonScript manifest SHOULD have a repository for the [canonical namespace](#namespace) of
that manifest, from which AddonScript implementations MAY check for updates for this addon.
### env_api

View file

@ -25,14 +25,15 @@ of the related addon are targeted by this relation.
### namespace
This is the [namespace](../concepts/namespaces.md) of the related addon. This property will be implicitly equal to the
[namespace of the addon](manifest.md#namespace), if it was not set explicitly.
This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the related addon. If this property is not set,
AddonScript will resolve the namespace via the [addon endpoint](../api/features/addons.md#get-addon) of a [repository](#repositories).
### repositories
This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript will try to get this relation from,
in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by
the namespace from all [defined repositories](manifest.md#repositories).
This is an array of [repository namespaces](repository.md#namespace). These are the repositories, from which AddonScript will try to get this relation from,
in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation from
the repository described by the [manifest namespace](manifest.md#namespace). The repository described the the [canonical namespace](#namespace) of this
relation has always precedence before these repositories.
### flags

View file

@ -2,17 +2,20 @@
```json
{
"id": "asrepo",
"url": "https://api.addonscript.net"
"namespace": "net.addonscript",
"instances": ["https://api.addonscript.net"]
}
```
## Required properties
### id
### namespace
This is the ID of the repository. It MUST be unique in the [manifest](manifest.md).
This is the [namespace](../concepts/namespaces.md), which describes this repository.
### url
### instances
This is the base URL of an [AddonScript API](../api) instance.
This is an array of base URLs of [AddonScript API](../api) instances, on which this
repository can be found. To get an addon from this repository, AddonScript will
try to get it from the [addon endpoint](../api/features/addons.md#get-addon)
of these API instances in the order, in which they are specified in this array.