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

docs(api): moved into 'docs' folder and splitted into multiple files

This commit is contained in:
antifallobst 2023-08-18 18:05:12 +02:00
parent ec41a8c9c6
commit 577869deaa
Signed by: antifallobst
GPG Key ID: 2B4F402172791BAF
17 changed files with 355 additions and 378 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

378
API.md
View File

@ -1,378 +0,0 @@
# 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` - POST
- [X] `/verify` - POST
- [X] `/authenticate` - POST
- [X] `/delete` - DELETE
- [X] `/tokens` - DELETE
- [X] `/tokens` - GET
- [ ] `/follows` - GET
- [ ] `/followers` - GET
- `/user/{username}`
- [ ] `/info` - GET
- [ ] `/follow` - POST
- [ ] `/follows` - GET
- [ ] `/followers` - GET
- [ ] `/projects` - GET
- `/project`
- [ ] `/create` - POST
- `/{projectname}`
- [ ] `/info` - GET
- [ ] `/join` - POST
## Endpoints
### `/account/register` - POST
Requests a new nerdcult account.
This sends a verification E-Mail which contains a link to the veriication frontend with an verification token as url parameter.
This verification link will time out after 10 minutes.
#### HTTP Headers
| Header | Content |
|--------------|--------------------|
| Content-Type | `application/json` |
#### Content - JSON
| Field | Description |
|----------|----------------------------------------|
| username | The accounts username / userid. |
| password | The password used for authentication. |
| email | The email address used for validation. |
#### Responses
##### 200 - Success
The verification request was sent.
##### 400 - Error: Bad Request
The request was malformed.
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 409 - Error: Conflict
The requested username or email is already taken.
__Content - JSON:__
| Field | Description |
|----------|----------------------------------------------------------------------|
| conflict | Can be `username` or `email`, depending on what caused the conflict. |
##### 422 - Error: Unprocessable Entity
Malformed email address.
### `/account/verify` - POST
Verifies a requested account.
#### HTTP Headers
| Header | Content |
|--------------|--------------------|
| Content-Type | `application/json` |
#### Content - JSON
| Field | Description |
|-------|--------------------------------------------------------------------------------|
| token | The verification token you received via an email after requesting the account. |
#### Responses
##### 200 - Success
The account was verified. You can login now.
##### 400 - Error: Bad Request
The request was malformed.
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Forbidden
The provided token is unknown.
### `/account/authenticate` - POST
Generates an authentication token for an account.
#### HTTP Headers
| Header | Content |
|--------------|--------------------|
| Content-Type | `application/json` |
#### Content - JSON
| Field | Description |
|----------|---------------------------------|
| username | The accounts username / userid. |
| password | The accounts password. |
#### Responses
##### 200 - Success
The authentication was successfull.
__Content - JSON:__
| Field | Description |
|-------|------------------------|
| token | A unique access token. |
##### 400 - Error: Bad Request
The request was malformed.
##### 401 - Error: Unauthorized
The provided password was wrong.
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The provided username was not found.
##### 424 - Error: Failed Dependency
The account isn't verified yet.
### `/account/delete` - DELETE
Deletes the account.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
#### Responses
##### 200 - Success
The account was deleted.
##### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
##### 403 - Error: Forbidden
Blocked for security reasons.
### `/account/tokens` - DELETE
Deletes a token of the authenticated account.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
#### Content - JSON
| Field | Description |
|-------|-----------------------------------|
| token | The token that should be deleted. |
#### Responses
##### 200 - Success
The token was deleted.
##### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The token that should be deleted wasn't found.
### `/account/tokens` - GET
Lists all active auth tokens for the account.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|--------|-------------------------------------------------------------------------------------------------|
| tokens | A list of (token, expiration date) pairs. The expiration date is given as a UTC UNIX timestamp. |
##### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
##### 403 - Error: Forbidden
Blocked for security reasons.
### `/account/follows` - GET
Lists all acccounts that the authenticated account follows.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
##### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
##### 403 - Error: Forbidden
Blocked for security reasons.
### `/account/followers` - GET
Lists all acccounts that are following the authenticated account.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
##### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
##### 403 - Error: Forbidden
Blocked for security reasons.
### `/user/{username}/info` - GET
Returns information about the user.
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------------------------------------|
| id | The users unique id. |
| name | The users unique username. |
| joined | The datetime when the user joined. Represented as UNIX timestamp. |
| is_admin | A boolean if the user is an admin. |
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The user wasn't found.
### `/user/{username}/follow` - POST
Let the authenticated account follow the user.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
#### Responses
##### 200 - Success
Successfully followed the user.
##### 208 - Already Reported
You already follow the user.
##### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The user wasn't found.
### `/user/{username}/follows` - GET
Returns the list of accounts the user is following.
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The user wasn't found.
### `/user/{username}/followers` - GET
Returns the list of accounts following the user.
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The user wasn't found.
### `/user/{username}/projects` - GET
Returns the list of public projects the user is part of.
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------------|
| projects | A list of (projectname, projectid) pairs. |
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The user wasn't found.
### `/project/create` - POST
Creates a new project.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
#### Content - JSON
| Field | Description |
|-------------|-----------------------------------------------|
| name | The name of the project to be created. |
| description | The description of the project to be created. |
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|-------|---------------------------------|
| id | The created projects unique id. |
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 409 - Error: Conflict
The requested project name is already taken.
### `/project/{projectname}/info` - GET
Returns the list of public projects the user is part of.
#### Responses
##### 200 - Success
__Content - JSON:__
| Field | Description |
|-------------|---------------------------------------------------------------------------|
| id | The projects unique id. |
| name | The projects unique name. |
| description | The projects description. |
| created | The datetime when the project was created. Represented as UNIX timestamp. |
| members | A list of (username, userid) pairs. |
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The project wasn't found.
### `/project/{projectname}/join` - POST
Returns the list of public projects the user is part of.
#### HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
#### Content - JSON
| Field | Description |
|---------|-----------------------------------------------------------|
| message | The request message the projects maintainers will review. |
#### Responses
##### 200 - Success
Your request will be reviewed.
##### 208 - Already Reported
You already joined the project.
##### 403 - Error: Forbidden
Blocked for security reasons.
##### 404 - Error: Not Found
The project wasn't found.

34
docs/API.md Normal file
View File

@ -0,0 +1,34 @@
# 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`
- `/user/{username}`
- [ ] `/info`
- [ ] `/follow`
- [ ] `/follows`
- [ ] `/followers`
- [ ] `/projects`
- `/project`
- [ ] `/create`
- `/{projectname}`
- [ ] `/info`
- [ ] `/join`
## TODO
- Password checking on registration
- usage examples
- anonymized account deletion reason
- account deactivation
- account bound rate limit
- id support for user and project specific calls

33
docs/account/authenticate.md Normal file
View File

@ -0,0 +1,33 @@
# `/account/authenticate` - POST
Generates an authentication token for an account.
## HTTP Headers
| Header | Content |
|--------------|--------------------|
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|----------|------------------------|
| username | The accounts username. |
| password | The accounts password. |
## Responses
### 200 - Success
The authentication was successfull.
__Content - JSON:__
| Field | Description |
|-------|------------------------|
| token | A unique access token. |
### 400 - Error: Bad Request
The request was malformed.
### 401 - Error: Unauthorized
The provided password was wrong.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The provided username was not found.
### 424 - Error: Failed Dependency
The account isn't verified yet.

15
docs/account/delete.md Normal file
View File

@ -0,0 +1,15 @@
# `/account/delete` - DELETE
Deletes the account.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
The account was deleted.
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.

18
docs/account/followers.md Normal file
View File

@ -0,0 +1,18 @@
# `/account/followers` - GET
Lists all acccounts that are following the authenticated account.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.

18
docs/account/follows.md Normal file
View File

@ -0,0 +1,18 @@
# `/account/follows` - GET
Lists all acccounts that the authenticated account follows.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.

33
docs/account/register.md Normal file
View File

@ -0,0 +1,33 @@
# `/account/register` - POST
Requests a new nerdcult account.
This sends a verification E-Mail which contains a link to the veriication frontend with an verification token as url parameter.
This verification link will time out after 10 minutes.
## HTTP Headers
| Header | Content |
|--------------|--------------------|
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|----------|----------------------------------------|
| username | The accounts username / userid. |
| password | The password used for authentication. |
| email | The email address used for validation. |
## Responses
### 200 - Success
The verification request was sent.
### 400 - Error: Bad Request
The request was malformed.
### 403 - Error: Forbidden
Blocked for security reasons.
### 409 - Error: Conflict
The requested username or email is already taken.
__Content - JSON:__
| Field | Description |
|----------|----------------------------------------------------------------------|
| conflict | Can be `username` or `email`, depending on what caused the conflict. |
### 422 - Error: Unprocessable Entity
Malformed email address.

43
docs/account/tokens.md Normal file
View File

@ -0,0 +1,43 @@
# `/account/tokens` - GET
Lists all active auth tokens for the account.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|--------|-------------------------------------------------------------------------------------------------|
| tokens | A list of (token, expiration date) pairs. The expiration date is given as a UTC UNIX timestamp. |
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.
# `/account/tokens` - DELETE
Deletes a token of the authenticated account.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|-------|-----------------------------------|
| token | The token that should be deleted. |
## Responses
### 200 - Success
The token was deleted.
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The token that should be deleted wasn't found.

22
docs/account/verify.md Normal file
View File

@ -0,0 +1,22 @@
# `/account/verify` - POST
Verifies a requested account.
## HTTP Headers
| Header | Content |
|--------------|--------------------|
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|-------|--------------------------------------------------------------------------------|
| token | The verification token you received via an email after requesting the account. |
## Responses
### 200 - Success
The account was verified. You can login now.
### 400 - Error: Bad Request
The request was malformed.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Forbidden
The provided token is unknown.

25
docs/project/create.md Normal file
View File

@ -0,0 +1,25 @@
# `/project/create` - POST
Creates a new project.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|-------------|-----------------------------------------------|
| name | The name of the project to be created. |
| description | The description of the project to be created. |
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|-------|---------------------------------|
| id | The created projects unique id. |
### 403 - Error: Forbidden
Blocked for security reasons.
### 409 - Error: Conflict
The requested project name is already taken.

17
docs/project/specific/info.md Normal file
View File

@ -0,0 +1,17 @@
# `/project/{projectname}/info` - GET
Returns the list of public projects the user is part of.
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|-------------|---------------------------------------------------------------------------|
| id | The projects unique id. |
| name | The projects unique name. |
| description | The projects description. |
| created | The datetime when the project was created. Represented as UNIX timestamp. |
| members | A list of (username, userid) pairs. |
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The project wasn't found.

23
docs/project/specific/join.md Normal file
View File

@ -0,0 +1,23 @@
# `/project/{projectname}/join` - POST
Lets the authenticated account join the project.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|---------|-----------------------------------------------------------|
| message | The request message the projects maintainers will review. |
## Responses
### 200 - Success
Your request will be reviewed.
### 208 - Already Reported
You already joined the project.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The project wasn't found.

19
docs/user/specific/follow.md Normal file
View File

@ -0,0 +1,19 @@
# `/user/{username}/follow` - POST
Let the authenticated account follow the user.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
Successfully followed the user.
### 208 - Already Reported
You already follow the user.
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The user wasn't found.

13
docs/user/specific/followers.md Normal file
View File

@ -0,0 +1,13 @@
# `/user/{username}/followers` - GET
Returns the list of accounts following the user.
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The user wasn't found.

13
docs/user/specific/follows.md Normal file
View File

@ -0,0 +1,13 @@
# `/user/{username}/follows` - GET
Returns the list of accounts the user is following.
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------|
| accounts | A list of (username, userid) pairs. |
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The user wasn't found.

16
docs/user/specific/info.md Normal file
View File

@ -0,0 +1,16 @@
# `/user/{username}/info` - GET
Returns information about the project.
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------------------------------------|
| id | The users unique id. |
| name | The users unique username. |
| joined | The datetime when the user joined. Represented as UNIX timestamp. |
| is_admin | A boolean if the user is an admin. |
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The user wasn't found.

13
docs/user/specific/projects.md Normal file
View File

@ -0,0 +1,13 @@
# `/user/{username}/projects` - GET
Returns the list of public projects the user is part of.
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|----------|-------------------------------------------|
| projects | A list of (projectname, projectid) pairs. |
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The user wasn't found.