api/docs/README.md

# 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 acquired using the `/account/authenticate` endpoint.

## Implementation Status

__(ND)__ -> Not designed yet.

- `/account`
    - [X] `/register`
    - [X] `/verify`
    - [X] `/authenticate`
    - [X] `/delete`
    - [X] `/id`
    - [X] `/tokens`
    - [ ] `/follows`
    - [ ] `/followers`
    - [ ] `/deactivate`
    - [ ] `/activate`
- `/user`
    - [X] `/info`
    - [ ] `/follow`
    - [ ] `/follows`
    - [ ] `/followers`
    - [ ] `/projects`
- `/project`
    - [X] `/create`
    - [X] `/delete`
    - [X] `/info`
    - [ ] `/join`
- `/vault`
    - [ ] `/info`
    - [ ] `/init`
    - [ ] `/key`
    - `/fs`
        - [ ] `/create` (ND)
        - [ ] `/read` (ND)
        - [ ] `/write` (ND)
        - [ ] `/info` (ND)
        - [ ] `/delete` (ND)
- `/admin`
    - `/backup`
        - [ ] `/list`
        - [ ] `/fetch/{id}`
        - [ ] `/create`
    - [ ] `/servers` (ND)
    - [ ] `/overview` (ND)

## 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
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 73
Content-Type: application/json
Host: api.nerdcult.net
User-Agent: HTTPie/3.2.1

{
    "email": "test@not.existing",
    "password": "pwd",
    "username": "username"
}


HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 0
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
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 45
Content-Type: application/json
Host: api.nerdcult.net
User-Agent: HTTPie/3.2.1

{
    "token": "f68b0ee33bbe4850991993c361997003"
}


HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 0
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
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 43
Content-Type: application/json
Host: api.nerdcult.net
User-Agent: HTTPie/3.2.1

{
    "password": "pwd",
    "username": "username"
}


HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 44
Content-Type: application/json
Date: Sun, 20 Aug 2023 13:44:17 GMT
Server: nginx/1.24.0
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
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Bearer f11f952c9d734461a11b087a27a219e2
Connection: keep-alive
Content-Length: 0
Host: api.nerdcult.net
User-Agent: HTTPie/3.2.1



HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 0
Date: Sun, 20 Aug 2023 13:54:30 GMT
Server: nginx/1.24.0
Strict-Transport-Security: max-age=31536000; includeSubDomains
```

## TODO

- account bound rate limit