Merge pull request 'Repository and Namespace improvements' (#27) from tilera/addonscript-spec:repos into master

Reviewed-on: addonscript/addonscript-spec#27
This commit is contained in:
Timo Ley 2022-09-26 08:19:25 +00:00
commit 14aa5338d2
8 changed files with 72 additions and 45 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
@ -37,4 +37,15 @@ 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.
- `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

@ -10,7 +10,8 @@ This endpoint can be used to build the launch environment for an [instance addon
If an [instance addon](../../concepts/instance.md), which has to provide a launch configuration, has the
`env` [manifest flag](../../concepts/flags.md#manifest-flags), AddonScript will send a request to this
endpoint if the API instance [specified in the manifest](../../schema/manifest.md#envapi) of that addon.
endpoint of an API instance, on which the [repository](../../schema/repository.md) of the
[namespace](../../schema/manifest.md#namespace) of this addon can be found.
This request contains information about the AddonScript [schema version](../../schema/api_env_request.md#addonscript),
which will be used in the request and about which [addon](../../schema/api_env_request.md#addon) this request is for.
Moreover it contains for both sides a list of addons, including their version, which will be part of the
@ -19,7 +20,7 @@ of this [addon](../../schema/api_env_request.md#addon) uses the `env` [relation
to tell AddonScript, which [related addons](../../schema/relation.md) MAY and which MUST be requested on this endpoint
and which [versions](../../schema/relation.md#version) of them are valid. Which exact version of them and which optional
addons will be requested is either decided by the user, if the instance addon is installed manually, or by another
[instance addon](../../concepts/instance.md), which delegates the launch configuration to this addon. In latetr case,
[instance addon](../../concepts/instance.md), which delegates the launch configuration to this addon. In later case,
that [instance addon](../../concepts/instance.md) uses the `env` [relation flag](../../concepts/flags.md#relational-flags)
to specify an exact version for each addon, that will be requested. Each required `env` addon MUST be covered this way
while only those optional `env` addons will be requested, which are covered this way. Lastly the request also contains
@ -46,6 +47,11 @@ The request body MUST be an [Environment Builder Request Object](../../schema/ap
- `200 OK`: The launch environment was successfully build.
The response body MUST be an [Environment Builder Response Object](../../schema/api_env_response.md).
- `400 Bad Request`: The server was not able to build the launch environment because of
invalid information sned by the client.
invalid information send by the client. The client SHOULD NOT try this request on
another API instance, since the request is invalid.
- `404 Not Found`: The launch environment can't be build for this addon, because no information
about it was found on this API instance. The client SHOULD try to use another API instance
to build the environment.
- `500 Internal Server Error`: The server was not able to build the launch environment
because of an internal error.
because of an internal error. The client MAY try to request the environment on another
API instance.

View file

@ -19,7 +19,8 @@ addon manifest, including for which side it is available and for which side it i
- `instance` This flag specifies, that this is a manifest of an [instance addon](instance.md).
- `env` This flag is only valid for [instance addons](instance.md). It specifies, that the
[environment builder API](../api/features/env.md) will be used to get the launch files for this addon.
An addon with this flag MUST have the [env_api](../schema/manifest.md#envapi) property.
An addon with this flag MUST have a [repository](../schema/repository.md) for it's
[canonical namespace](../schema/manifest.md#namespace).
## Relational flags

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

View file

@ -10,7 +10,6 @@
"relations": [],
"flags": {},
"repositories": [],
"env_api": "https://example.com",
"meta": {}
}
```
@ -52,13 +51,10 @@ 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.
### env_api
This is the base URL of an [AddonScript API](../api) instance, which has the `env` feature and will be used to
build the launch environment for this addon. This property will only be used if this addon has the `env`
[manifest flag](../concepts/flags.md#manifest-flags).
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. If this addon has the `env`
[manifest flag](../concepts/flags.md#manifest-flags), it MUST have such a repository to provide API instances, which can
be used to request the [launch environment](../api/features/env.md#build-launch-environment).
### meta

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,25 @@
```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.
Instances in this array with the `env` [feature](../api/features/env.md) will
be used by AddonScript, to request the launch environment for an addon with a
[canonical namespace](../concepts/namespaces.md#canonical-namespaces) equal
to the [namespace](#namespace) of this repository. The first API instance with
the `env` feature will be used in this case with the others as fallback.