diff --git a/docs/README.md b/docs/README.md index c5e7adc..0f0657a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,19 @@ # API + All API endpoints are accessible with this base URL: `https://api.nerdcult.net/`. Some API endpoints require an Authorization HTTP header. The token for this can be aquired using the `/account/authenticate` endpoint. ## Implementation Status -__(ND)__ -> Not designed yet. +__(ND)__ -> Not designed yet. - `/account` - [X] `/register` - [X] `/verify` - [X] `/authenticate` - [X] `/delete` - - [ ] `/id` + - [X] `/id` - [X] `/tokens` - [X] `/tokens` - [ ] `/follows` @@ -47,10 +48,12 @@ __(ND)__ -> Not designed yet. - [ ] `/create` ## Examples + An example _Register -> Verify -> Authenticate -> Delete_ flow. The examples use the [HTTPie](https://httpie.io/) CLI. ### 1. Register a new account + ``` $ http -v POST https://api.nerdcult.net/account/register email=test@not.existing password=pwd username=username POST /account/register HTTP/1.1 @@ -76,10 +79,12 @@ Date: Sun, 20 Aug 2023 13:37:35 GMT Server: nginx/1.24.0 Strict-Transport-Security: max-age=31536000; includeSubDomains ``` + This sends a verification token to the email you specified in the request body. Such a token looks like this: `f68b0ee33bbe4850991993c361997003`. ### 2. Verify the created account + ``` $ http -v POST https://api.nerdcult.net/account/verify token="f68b0ee33bbe4850991993c361997003" POST /account/verify HTTP/1.1 @@ -103,9 +108,11 @@ Date: Sun, 20 Aug 2023 13:41:51 GMT Server: nginx/1.24.0 Strict-Transport-Security: max-age=31536000; includeSubDomains ``` + The account is now verified and functional. ### 3. Get an access token + ``` $ http -v POST https://api.nerdcult.net/account/authenticate username=username password=pwd POST /account/authenticate HTTP/1.1 @@ -135,11 +142,14 @@ Strict-Transport-Security: max-age=31536000; includeSubDomains "token": "f11f952c9d734461a11b087a27a219e2" } ``` + This token can now be used to call other API calls. It will expire after 7 days. ### 4. Delete the account + This is an example for an action that needs authentication. + ``` $ http -v DELETE https://api.nerdcult.net/account/delete -A bearer -a f11f952c9d734461a11b087a27a219e2 DELETE /account/delete HTTP/1.1 @@ -162,4 +172,5 @@ Strict-Transport-Security: max-age=31536000; includeSubDomains ``` ## TODO + - account bound rate limit