From 2b2e30a72f8657499c5a48f046501cad3bc86de7 Mon Sep 17 00:00:00 2001
From: DavHau <d.hauer.it@gmail.com>
Date: Fri, 1 Dec 2023 16:27:44 +0700
Subject: [PATCH] docs: add API guidelines

---
 docs/api-guidelines.md | 138 +++++++++++++++++++++++++++++++++++++++++
 docs/contributing.md   |   4 ++
 2 files changed, 142 insertions(+)
 create mode 100644 docs/api-guidelines.md

diff --git a/docs/api-guidelines.md b/docs/api-guidelines.md
new file mode 100644
index 000000000..0f105d0ab
--- /dev/null
+++ b/docs/api-guidelines.md
@@ -0,0 +1,138 @@
+# API Guidelines
+
+This issue serves to collect our common understanding how to design our API so that it is extensible and usable and understandable.
+
+## Resource oriented
+
+A resource-oriented API is generally modeled as a resource hierarchy, where each node is either a simple resource or a collection resource. For convenience, they are often called a resource and a collection, respectively.
+
+Examples of Resource Nouns:
+
+`machine`
+`user`
+`flake`
+
+Often resources have sub-resources. Even if it is not foreseen, it is recommended to use plural (trailing `s`) on resources to allow them to be collections of sub-resources.
+
+e.g,
+
+`users`
+->
+`users/*/profile`
+
+## Verbs
+
+Verbs should not be part of the URL
+
+Bad:
+`/api/create-products`
+
+Good:
+`/api/products`
+
+Only resources are part of the URL, verbs are described via the HTTP Method.
+
+Exception:
+
+If a different HTTP Method must be used for technical reasons it is okay to terminate the path with a (short) verb / action.
+
+Okay ish:
+`/api/products/create`
+
+## Usually the following HTTP Methods exist to interact with a resource
+
+- POST (create an order for a resource)
+- GET (retrieve the information)
+- PUT (update and replace information)
+- PATCH (update and modify information) **(Not used yet)**
+- DELETE (delete the item)
+
+## Every resource should be CRUD compatible
+
+All API resources MUST be designed in a way that allows the typical CRUD operations.
+
+Where crud stands for:
+
+C - Create
+R - Read
+U - Update
+D - Delete
+
+Resources should implement at least a "Read" operation.
+
+## Body
+
+Use JSON as an exchange format.
+
+All responses MUST be JSON parseable.
+
+Bad:
+`bare string`
+
+Better:
+`"quoted string"`
+
+Best: (Enveloped see next section)
+`{ name: "quoted string"}`
+
+Errors should have a consistent JSON format, such that it is clear in which field to look at for displaying error messages.
+
+## Envelop all Data collections
+
+Response data should be wrapped into an JSON Object `{}`
+Lists `[]` should also contain Objects `{}`.
+This allows everything, to be extensible, without breaking backwards compatibility. (Adding fields is trivial, since the schema doesn't change)
+
+Example:
+
+```
+{
+   "users": [{
+     first_name: "John",
+     last_name: "Doe",
+     …
+   }, {
+     first_name: "Jane",
+     last_name: "Doe",
+     …
+   }
+  ....
+  ],
+   "skip": 0,
+   "limit": 20,
+  ....
+}
+```
+
+Bad Example of a breaking change:
+`GET /api/flakes`
+`old`
+
+```
+[
+  "dream2nix"
+  "disko"
+]
+```
+
+`new`
+
+```
+[
+ {
+    name: "dream2nix",
+    url: "github/...."
+ },
+ {
+    name: "disko",
+    url: "github/...."
+ }
+]
+```
+
+Those kind of breaking changes can be avoided by using an object from the beginning.
+Even if the object only contains one key, it is extensible, without breaking.
+
+## More will follow.
+
+...maybe
diff --git a/docs/contributing.md b/docs/contributing.md
index 342d9eddf..e6d094e0a 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -221,3 +221,7 @@ To make the most of this template:
    - Also, set the default merge style to "Rebase then create merge commit."
 
 With this template, you're well-equipped to build and collaborate on high-quality websites efficiently. Happy coding!.
+
+# API guidelines
+
+see [./api-guidelines](./api-guidelines)