API spec overhaul

docs/SUMMARY.md

@@ -5,6 +5,7 @@
 # API
 
 - [AddonScript API](api/README.md)
+  - [Addon repository](api/features/addons.md)
   - [File repository](api/features/files.md)
 
 # Schema
@@ -16,6 +17,8 @@
   - [Relation Object](schema/relation.md)
   - [Repository Object](schema/repository.md)
   - [Meta Object](schema/meta.md)
+- [API Addon](schema/api_addon.md)
+- [API File](schema/api_file.md)
 
 # Concepts
 

docs/api/README.md

@@ -6,63 +6,27 @@
 
 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](../concepts/namespaces.md) of the instance. 
+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.
 
 #### Example response body:
 
 ``` json
 {
+    "versions": {
+        "v2": {
             "default_namespace": "com.example",
-    "versions": ["v1"],
             "features": ["listing", "filters", "com.example.customfeature"]
         }
-```
-
-## Basic Endpoints
-
-### `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](../concepts/namespaces.md#canonical-namespaces) 
-of the addon. 
-
-#### Path variales:
-
-- `namespace`: A [namespace](../concepts/namespaces.md) which contains the addon
-- `addon`: The ID of the addon
-
-#### Example response body:
-
-``` json
-{
-    "id": "addon-id",
-    "namespace": "com.example.canonical",
-    "meta": {
-        "addon": {},
-        "additional": {}
-    },
-    "versions": [
-        "1.0"
-    ]
+    }
 }
 ```
 
-The [meta object](../schema/meta.md) is the same as in the AddonScript files,
-except, that it only includes `addon` and `additional` metadata and not `version`
-specific metadata.
-
-### `GET {base URL}/v1/addons/:namespace/:addon/:version`
-
-This endpoint can be used to retrieve a specific version of an addon.
-The response body of this endpoint contains the [addon schema](../schema/addon.md),
-which is also used in AddonScript JSON files.
-
-#### Path variables:
-
-- `namespace`: The namespace which contains the addon
-- `addon`: The ID of the addon
-- `version`: The [version number](../concepts/versioning.md) of the requested version
-
 ## Features
 
 API features can be either part of the specification itself or 
@@ -71,5 +35,5 @@ be in a namespace-like format (reversed domain name).
 
 These API features are part of the AddonScript specification itself:
 
+- `addons`: [Addon repository](./features/addons.md)
 - `files`: [File repository](./features/files.md)
-- To be added

docs/api/features/addons.md

@@ -0,0 +1,40 @@
+# Addon repository
+
+## Endpoints 
+
+### Get addon
+
+`GET {base URL}/v2/addons/:namespace/:addon`
+
+This endpoint can be used to retrieve information about a specific addon,
+including metadata, all available versions and the [canonical namespace](../../concepts/namespaces.md#canonical-namespaces) 
+of the addon. 
+
+#### Path variales:
+
+- `namespace`: A [namespace](../../concepts/namespaces.md) which contains the addon
+- `addon`: The ID of the addon
+
+#### Responses:
+
+- `200 OK`: The addon is available in this addon repository. 
+The response body must be an [API Addon Object](../../schema/api_addon.md).
+- `404 Not Found`: The addon is not available in this addon repository.
+
+### Get addon manifest
+
+`GET {base URL}/v2/addons/:namespace/:addon/:version`
+
+This endpoint can be used to retrieve the manifest of a specific version of an addon.
+
+#### Path variables:
+
+- `namespace`: The namespace which contains the addon
+- `addon`: The ID of the addon
+- `version`: The [version number](../../concepts/versioning.md) of the requested version
+
+#### Responses:
+
+- `200 OK`: This version of the addon is available in this addon repository.
+The response body must be an [Addon Manifest](../../schema/addon.md).
+- `404 Not Found`: This version of the addon is not available in this addon repository.

docs/api/features/files.md

@@ -2,7 +2,9 @@
 
 ## Endpoints
 
-### `GET {base URL}/v1/files/:namespace/:addon/:version/:qualifier`
+### Get a file by identifier
+
+`GET {base URL}/v2/files/:namespace/:addon/:version/:qualifier`
 
 This endpoint can be used to retrieve information about a specific file.
 If the instance don't know this file, it must respond with status code 404.
@@ -15,22 +17,15 @@ of the addon to which the file belongs to
 - `version`: The addon version to which the file belongs to
 - `qualifier`: The qualifier of the file
 
-#### Example response:
+#### Responses:
 
-```json
-{
-    "links": ["https://example.com/file.jar"],
-    "filename?": "file.jar",
-    "hashes": {
-        "sha1": "somesha1checksum"
-    },
-    "meta": {
-        "additional": {}
-    }
-}
-```
+- `200 OK`: The file is available in this file repository.
+The response body must be an [API File Object](../../schema/api_file.md).
+- `404 Not Found`: The file is not available in this file repository.
 
-### `GET {base URL}/v1/files/:algorithm/:hash`
+### Get a file by hash
+
+`GET {base URL}/v2/files/:algorithm/:hash`
 
 This endpoint can be used to retrieve information about a file from the hash value of the file.
 If the instance can't find the file by the hash or does not know the specified hash algorithm,
@@ -41,17 +36,9 @@ it must respond with status code 404.
 - `algorithm`: The hash algorithm of the hash
 - `hash`: The hash value of the file
 
-#### Example response:
+#### Responses:
 
-```json
-{
-    "links": ["https://example.com/file.jar"],
-    "filename?": "file.jar",
-    "hashes": {
-        "sha1": "somesha1checksum"
-    },
-    "meta": {
-        "additional": {}
-    }
-}
-```
+- `200 OK`: The file is available in this file repository.
+The response body must be an [API File Object](../../schema/api_file.md).
+- `404 Not Found`: The file is either not available in this file repository
+or the hash algorithm is unknown to the API instance.

docs/concepts/namespaces.md

@@ -13,14 +13,14 @@ optionally also the addon type (i.e. `com.example.repository.mods`, `com.author.
 
 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)
+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, thier canonical namespace and their ID must be equal.
 
 ## Default Namespaces
 
-Each [API instance](../api/README.md) has a default namespace. Addons in the 
+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. 

docs/schema/api_addon.md

@@ -0,0 +1,39 @@
+# API Addon Object
+
+```json
+{
+    "id": "myaddon",
+    "namespace": "com.example",
+    "meta": {
+        "addon": {},
+        "additional": {}
+    },
+    "versions": [
+        "1.0"
+    ]
+}
+```
+
+## Required properties
+
+### id
+
+This is the ID of the addon.
+
+It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
+
+### namespace
+
+This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the addon.
+
+### versions
+
+This is an array of all [version numbers](../concepts/versioning.md) of this addon, which are
+available on this API instance.
+
+## Optional properties
+
+### meta 
+
+This is a [meta object](meta.md) containing metadata about the addon. It does not
+contain any version specific metadata.

docs/schema/api_file.md

@@ -0,0 +1,34 @@
+# API File Object
+
+```json
+{
+    "link": ["https://example.com/file.jar"],
+    "hashes": {
+        "sha1": "somesha1checksum"
+    },
+    "meta": {
+        "additional": {}
+    }
+}
+```
+
+## Required properties
+
+### link
+
+This is an array of [links](../concepts/links.md), which are pointing to the actual file. This must be a http(s) link.
+All of these links must have the same file type.
+
+## Optional properties
+
+### hashes
+
+This is an object with checksums for this file. The object contains key-value-pairs where the key is the hash algorithm and the
+value is the checksum. 
+
+Supported hash algorithms:
+- `sha1`
+
+### meta
+
+This is a [meta object](meta.md) containing metadata about the file. it may only contain [additional metadata](meta.md#additional).

docs/schema/file.md

@@ -27,8 +27,8 @@ This is an array of [links](../concepts/links.md), which are pointing to the act
 have the same file type. Since AddonScript treats directories and zip files equally, 
 they can be mixed in the same link array. When downloading the file,
 the first link in this array should be used with the other links as fallback, if the first doesn't work.
-If none of the specified links works, the file should be downloaded by it's Maven
-specifier from one of the specified repository, but only, if a `sha1` hash is specified, so that it can be
+If none of the specified links works or the array is empty, the file link should be retrieved by it's identifier
+from one of the [repositories](repository.md), but only, if a `sha1` hash is specified, so that it can be
 verified, that the downloaded file is correct. 
 
 ## Optional properties