History

antifallobst ce4fe91f7d feat: enforcing alphanumerical usernames		2023-10-11 12:32:01 +02:00
..
account	feat: enforcing alphanumerical usernames	2023-10-11 12:32:01 +02:00
admin	docs(api): defined some endpoints	2023-09-26 17:58:24 +02:00
project	docs(api): defined and designed /account/id	2023-09-10 13:44:51 +02:00
user	refactor(api): renamend the field `name` of /user/id to `username`	2023-09-13 07:23:26 +02:00
vault	docs(api): designed the basic vault endpoints	2023-09-09 00:18:58 +02:00
README.md	docs(api): defined some endpoints	2023-09-26 17:58:24 +02:00

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
- /register
- /verify
- /authenticate
- /delete
- /id
- /tokens
- /follows
- /followers
- /deactivate
- /activate
/user
- /info
- /follow
- /follows
- /followers
- /projects
/project
- /create
- /delete
- /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 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