basic namespace spec

This commit is contained in:
Timo Ley 2022-08-04 16:53:33 +02:00
parent 123f62e1c2
commit a4ec67e76c
3 changed files with 34 additions and 10 deletions

View file

@ -6,7 +6,7 @@
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.
instance and the default [namespace](../concepts/namespaces.md) of the instance.
#### Example response body:
@ -23,12 +23,12 @@ instance and the default namespace of the instance.
### `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.
including metadata, all available versions and the [canonical namespace](../concepts/namespaces.md#canonical-namespaces)
of the addon.
#### Path variales:
- `namespace`: The namespace which contains the addon
- `namespace`: A [namespace](../concepts/namespaces.md) which contains the addon
- `addon`: The ID of the addon
#### Example response body:
@ -48,7 +48,7 @@ the addon.
```
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`
except, that it only includes `addon` and `additional` metadata and not `version`
specific metadata.
### `GET {base URL}/v1/addons/:namespace/:addon/:version`

View file

@ -1 +1,26 @@
# Namespaces
Namespaces are used in conjunction with addon IDs to uniquely identify an addon.
## Format
Namespaces may only contain lowercase alphanumeric characters, hyphens (should be avoided) and dots.
They should be in a reversed domain name format. A namespace should specify the distribution source
(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`).
## Canonical Namespaces
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)
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
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

@ -33,6 +33,10 @@ This is the [version number](../concepts/versioning.md) of this version. Version
[Maven version order rules](../concepts/versioning.md#version-order-specification).
If this version number is valid semver, the `semver` property is implicitly equal to `version` if `semver` was not explicitly set.
### namespace
This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the addon.
### flags
This is an array of [flags](../concepts/flags.md) for this version.
@ -43,11 +47,6 @@ This is an array of [flags](../concepts/flags.md) for this version.
This is the version number of this version in semver format. It must follow the [semver versioning specifications](https://semver.org/spec/v2.0.0.html).
### namespace
This is the [namespace](../concepts/namespaces.md) of the addon, which should be in a reversed domain name format.
Used to identify addons across repositories.
### files
This is an array of [file objects](file.md) including the files belonging to this addon.