146 lines
3.5 KiB
Markdown
146 lines
3.5 KiB
Markdown
# 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
|
|
- `/account`
|
|
- [X] `/register`
|
|
- [X] `/verify`
|
|
- [X] `/authenticate`
|
|
- [X] `/delete`
|
|
- [X] `/tokens`
|
|
- [X] `/tokens`
|
|
- [ ] `/follows`
|
|
- [ ] `/followers`
|
|
- [ ] `/deactivate`
|
|
- [ ] `/activate`
|
|
- `/user/`
|
|
- [ ] `/info`
|
|
- [ ] `/follow`
|
|
- [ ] `/follows`
|
|
- [ ] `/followers`
|
|
- [ ] `/projects`
|
|
- `/project`
|
|
- [ ] `/create`
|
|
- [ ] `/info`
|
|
- [ ] `/join`
|
|
|
|
## 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 an 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
|
|
- Password checking on registration
|
|
- account bound rate limit |