From 577869deaafb6fc8db1acbe0532007a63dc89b0c Mon Sep 17 00:00:00 2001 From: antifallobst Date: Fri, 18 Aug 2023 18:05:12 +0200 Subject: [PATCH] docs(api): moved into 'docs' folder and splitted into multiple files --- API.md | 378 -------------------------------- docs/API.md | 34 +++ docs/account/authenticate.md | 33 +++ docs/account/delete.md | 15 ++ docs/account/followers.md | 18 ++ docs/account/follows.md | 18 ++ docs/account/register.md | 33 +++ docs/account/tokens.md | 43 ++++ docs/account/verify.md | 22 ++ docs/project/create.md | 25 +++ docs/project/specific/info.md | 17 ++ docs/project/specific/join.md | 23 ++ docs/user/specific/follow.md | 19 ++ docs/user/specific/followers.md | 13 ++ docs/user/specific/follows.md | 13 ++ docs/user/specific/info.md | 16 ++ docs/user/specific/projects.md | 13 ++ 17 files changed, 355 insertions(+), 378 deletions(-) delete mode 100644 API.md create mode 100644 docs/API.md create mode 100644 docs/account/authenticate.md create mode 100644 docs/account/delete.md create mode 100644 docs/account/followers.md create mode 100644 docs/account/follows.md create mode 100644 docs/account/register.md create mode 100644 docs/account/tokens.md create mode 100644 docs/account/verify.md create mode 100644 docs/project/create.md create mode 100644 docs/project/specific/info.md create mode 100644 docs/project/specific/join.md create mode 100644 docs/user/specific/follow.md create mode 100644 docs/user/specific/followers.md create mode 100644 docs/user/specific/follows.md create mode 100644 docs/user/specific/info.md create mode 100644 docs/user/specific/projects.md diff --git a/API.md b/API.md deleted file mode 100644 index 3b93ae7..0000000 --- a/API.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..4233bd3 --- /dev/null +++ b/docs/API.md @@ -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 \ No newline at end of file diff --git a/docs/account/authenticate.md b/docs/account/authenticate.md new file mode 100644 index 0000000..1e921b0 --- /dev/null +++ b/docs/account/authenticate.md @@ -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. \ No newline at end of file diff --git a/docs/account/delete.md b/docs/account/delete.md new file mode 100644 index 0000000..5951125 --- /dev/null +++ b/docs/account/delete.md @@ -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. diff --git a/docs/account/followers.md b/docs/account/followers.md new file mode 100644 index 0000000..1a98532 --- /dev/null +++ b/docs/account/followers.md @@ -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. \ No newline at end of file diff --git a/docs/account/follows.md b/docs/account/follows.md new file mode 100644 index 0000000..041ffdd --- /dev/null +++ b/docs/account/follows.md @@ -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. \ No newline at end of file diff --git a/docs/account/register.md b/docs/account/register.md new file mode 100644 index 0000000..62beb32 --- /dev/null +++ b/docs/account/register.md @@ -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. \ No newline at end of file diff --git a/docs/account/tokens.md b/docs/account/tokens.md new file mode 100644 index 0000000..408c4eb --- /dev/null +++ b/docs/account/tokens.md @@ -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. \ No newline at end of file diff --git a/docs/account/verify.md b/docs/account/verify.md new file mode 100644 index 0000000..e1a2b5d --- /dev/null +++ b/docs/account/verify.md @@ -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. \ No newline at end of file diff --git a/docs/project/create.md b/docs/project/create.md new file mode 100644 index 0000000..62fd4fb --- /dev/null +++ b/docs/project/create.md @@ -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. \ No newline at end of file diff --git a/docs/project/specific/info.md b/docs/project/specific/info.md new file mode 100644 index 0000000..91dd79e --- /dev/null +++ b/docs/project/specific/info.md @@ -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. diff --git a/docs/project/specific/join.md b/docs/project/specific/join.md new file mode 100644 index 0000000..ea6c7fd --- /dev/null +++ b/docs/project/specific/join.md @@ -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. \ No newline at end of file diff --git a/docs/user/specific/follow.md b/docs/user/specific/follow.md new file mode 100644 index 0000000..cab490f --- /dev/null +++ b/docs/user/specific/follow.md @@ -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. \ No newline at end of file diff --git a/docs/user/specific/followers.md b/docs/user/specific/followers.md new file mode 100644 index 0000000..813a899 --- /dev/null +++ b/docs/user/specific/followers.md @@ -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. \ No newline at end of file diff --git a/docs/user/specific/follows.md b/docs/user/specific/follows.md new file mode 100644 index 0000000..41868e7 --- /dev/null +++ b/docs/user/specific/follows.md @@ -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. \ No newline at end of file diff --git a/docs/user/specific/info.md b/docs/user/specific/info.md new file mode 100644 index 0000000..1e80b89 --- /dev/null +++ b/docs/user/specific/info.md @@ -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. \ No newline at end of file diff --git a/docs/user/specific/projects.md b/docs/user/specific/projects.md new file mode 100644 index 0000000..a614c1b --- /dev/null +++ b/docs/user/specific/projects.md @@ -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. \ No newline at end of file