docs: started to document single api entpoints

2024-03-23 18:57:50 +01:00 · 2024-03-23 18:57:50 +01:00 · 3ac7716826
parent e82dafd784
commit 3ac7716826
4 changed files with 62 additions and 17 deletions
--- a/docs/api.md
+++ b/docs/api.md
@ -1,17 +0,0 @@
-# ICRC API
-
-## Endpoint overview
-
- /account
-    - [X] `POST` /register
-    - [X] `POST` /auth
-    - [ ] `POST` /delete
-    - [ ] `GET`  /blob
-    - [ ] `POST` /blob
-    - /invite
-        - [X] `POST` /new
-        - [ ] `GET` /list
- /relay
-    - [X] `POST` /create
-    - [ ] `POST` /join
-    - [ ] `POST` /leave
--- a/docs/api/README.md
+++ b/docs/api/README.md
@ -0,0 +1,17 @@
+# ICRC API
+
+ICRC Clients use an HTTP API to communicate with the server, which is going to be described in this part of the ICRC
+docs.
+
+## Authentication
+
+Most API endpoints require you to ensure, that you have a user account.
+To do that, [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) is
+used. You can get Bearer tokens using
+the [`/account/auth`](https://git.nerdcult.net/antifallobst/icrc-server/src/branch/master/docs/api/endpoints/account/auth.md)
+endpoint.
+
+## Endpoints
+
+There are docs for every endpoint
+over [here](https://git.nerdcult.net/antifallobst/icrc-server/src/branch/master/docs/api/endpoints/).
--- a/docs/api/endpoints/README.md
+++ b/docs/api/endpoints/README.md
@ -0,0 +1,20 @@
+# API Endpoints
+
+**Disclaimer**:
+ICRC is currently work in progress. This means, that not all endpoints are implemented yet. An overview, which API
+endpoints are currently implemented can be found in [this](https://git.nerdcult.net/antifallobst/icrc-server/issues/2)
+tracking issue. Further, the specific design of endpoints can be subject to change, while the project is still under
+rapid development.
+
+This directory represents the API structure. Every endpoint has its own file and for every URL subdirectory there is a
+directory.
+
+## Overview
+
+- /account
+    - /register - POST
+    - /auth - POST
+    - /invite
+        - new - POST
+- /relay
+    - /create - POST
--- a/docs/api/endpoints/account/register.md
+++ b/docs/api/endpoints/account/register.md
@ -0,0 +1,25 @@
+# `/account/register`
+
+**Type:** POST  
+**Auth:** Yes  
+**Body:** JSON
+
+## Description
+
+This endpoint creates a new account. To do that, you need an invite-token, that someone who has an account with the
+needed permissions has to create for you. Invite-tokens can only be used within one week, before they expire.
+
+## Request Body
+
+| Field      | Description                                     |
+|------------|-------------------------------------------------|
+| `token`    | A valid invite token (48 alphanumerical chars). |
+| `password` | The password for the new account.               |
+
+## Responses
+
+| HTTP Code | Type               | Description                            | Body                                                                       |
+|-----------|--------------------|----------------------------------------|----------------------------------------------------------------------------|
+| 200       | Success            | The account was successfully created.  | Json containing only a `userid` field, which is needed for authentication. |
+| 401       | Error/InvalidToken | The invite-token is unknown / invalid. | Standard Error Body.                                                       |
+| 410       | Error/TokenExpired | The invite-token expired.              | Standard Error Body.                                                       |