nerdcult
/
api
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): added usage examples

This commit is contained in:
antifallobst 2023-08-20 15:56:14 +02:00
parent 2d7091f5d8
commit 722a58a2f3
Signed by: antifallobst
GPG Key ID: 2B4F402172791BAF
1 changed files with 115 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/README.md
View File

@ -26,7 +26,121 @@ The token for this can be aquired using the `/account/authenticate` endpoint.
- [ ] `/info`
- [ ] `/join`
## Examples
An example _Register -> Verify -> Authenticate -> Delete_ flow.
The exmples 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
- usage examples
- account bound rate limit