From b0d25a7018a2d2f5e88a1c8351bee6c0117349b2 Mon Sep 17 00:00:00 2001
From: Timo Ley <timo.ley@tilera.dev>
Date: Fri, 25 Feb 2022 22:54:10 +0100
Subject: [PATCH] Basic API specification

---
 docs/SUMMARY.md    |  4 +++
 docs/api/README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100755 docs/api/README.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 258578e..67b73e6 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -2,6 +2,10 @@
 
 - [AddonScript](README.md)
 
+# API
+
+- [API](api/README.md)
+
 # Schema
 
 - [Addon Object](schema/addon.md)
diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100755
index 0000000..8bfaf79
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,74 @@
+# The AddonScript API
+
+## The Index Endpoint
+
+### `GET {base URL}`
+
+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. 
+
+#### Example response body:
+
+``` json
+{
+    "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 of
+the addon. 
+
+#### Path variales:
+
+- `namespace`: The namespace 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,
+exept, 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 
+are specified by third parties. Third-party API features should
+be in a namespace-like format (reversed domain name).
+
+These API features are part of the AddonScript specification itself:
+
+- To be added
\ No newline at end of file