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

Reviewed-on: #27

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"]
         }
     }
 }

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

docs/api/features/env.md

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

docs/concepts/flags.md

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

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

docs/schema/manifest.md

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

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
 

docs/schema/repository.md

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