From 27ad758268a29fadf583006605146ab513224288 Mon Sep 17 00:00:00 2001 From: Timo Ley Date: Fri, 23 Sep 2022 18:33:14 +0200 Subject: [PATCH] Namespace and repository overhaul --- docs/api/README.md | 9 +++------ docs/api/features/addons.md | 17 ++++++++++++++--- docs/concepts/namespaces.md | 31 +++++++++++++++++++------------ docs/schema/manifest.md | 3 ++- docs/schema/relation.md | 11 ++++++----- docs/schema/repository.md | 15 +++++++++------ 6 files changed, 53 insertions(+), 33 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index 6a3284d..5f4df83 100755 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -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"] } } } diff --git a/docs/api/features/addons.md b/docs/api/features/addons.md index 711f03d..bca38f5 100644 --- a/docs/api/features/addons.md +++ b/docs/api/features/addons.md @@ -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. \ No newline at end of file +- `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. \ No newline at end of file diff --git a/docs/concepts/namespaces.md b/docs/concepts/namespaces.md index 471db7e..3a38d5a 100644 --- a/docs/concepts/namespaces.md +++ b/docs/concepts/namespaces.md @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/schema/manifest.md b/docs/schema/manifest.md index 8155519..9e4b95c 100644 --- a/docs/schema/manifest.md +++ b/docs/schema/manifest.md @@ -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 diff --git a/docs/schema/relation.md b/docs/schema/relation.md index daa9072..0ad4c87 100644 --- a/docs/schema/relation.md +++ b/docs/schema/relation.md @@ -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 diff --git a/docs/schema/repository.md b/docs/schema/repository.md index 851486c..c8d59d5 100644 --- a/docs/schema/repository.md +++ b/docs/schema/repository.md @@ -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. \ No newline at end of file +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. \ No newline at end of file