api/API.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 aquired using the /account/authenticate endpoint.

Implementation Status

• /account
  • /register - POST
  • /verify - POST
  • /authenticate - POST
  • /delete - DELETE
  • /tokens - DELETE
  • /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.