378 lines
12 KiB
Markdown
378 lines
12 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` - 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. |