Skip to content

API Documentation Guide

Jump to bottom
Daniel Dervishi edited this page Nov 26, 2023 · 7 revisions

The Mozilla Web Docs are a very helpful addition resource

You can remove all unused fields from documentation

API Documentation Example

API Name: [Your API Name]

[Method Name]

  • Route: [API Route]
  • HTTP Method: [HTTP Method (GET, POST, PUT, DELETE, etc.)]

Description

[Description of what this API endpoint does]

Request

[Specify request parameters, if any]

  • [Parameter 1]: [Description and type]
  • [Parameter 2]: [Description and type]
  • ...

Response

See https://github.com/omniti-labs/jsend for specifications on how to format json responses.

Data Storage/Modification

[Explain what data is stored or modified by this API]

Data Retrieval

[Explain what data can be retrieved using this API]

Data Deletion

[Explain what data can be deleted using this API]

Authorization API

Login, Logout, Creating Users

Login

  • Route: <backend_url>/login
  • HTTP Method: POST

Description

This API endpoint is used to log into the website as a user that has already been creating. This login uses an email/password combination

Request

  • username: string. The email of the account you are attempting to log in as
  • password: string. The plaintext password of the account you are attempting to log in as

Response

  • On success, the API redirects to the frontend's index page
  • On failure, the API redirects to the frontend's login page

Data Storage/Modification

On success, this API stores the user's email, and administrator status (is_admin) in a session using server-side SQL storage.

Data Retrieval

N/A

Data Deletion

N/A

Logout

logoutRequestHandler

  • Route: /logout
  • HTTP Method: POST

Description

Use this API to log out a user, clearing their session.

Request

N/A

Response

  • Success Response:
    • On success, this API redirects you to the index of the backend page
  • Error Response:
    • On failure, this API will throw an error (if we reach here, it means there is a fatal error with PassportJS -- if you are not logged in, and try to log out, it will still succeed.)

Data Storage/Modification

N/A

Data Retrieval

N/A

Data Deletion

Upon logging out, a user's session will be cleared from the server-side SQLite database

Create User

createUserRequestHandler

  • Route: /create_user
  • HTTP Method: POST

Description

This API is used to create new users. Only an admin account can create new users.

Request

  • first_name: string The first name of the created user
  • last_name: string The last name of the created user
  • email: string The email of the created user
  • password: string The plaintext password of the created user
  • ...

Response

[Specify the response format]

  • Success Response:

    • Status Code: 200
    • Data Returned: Message "User created successfully"

  • Error Response:

    • Status Code: 403 || 500
    • Data Returned: Error message relating to the error

Data Storage/Modification

On success, a new user is added to the Users table in the PlanetScale database matching the credentials that were passed into the function

Data Retrieval

N/A

Data Deletion

N/A

Users API

Create User, Update User, Get All Users, Get single User, Delete User

Update User

  • Route: <backend_url>/<user_id>
  • HTTP Method: PUT

Description

This API endpoint is used to update an existing user.

Request

  • [OPTIONAL] first_name: string. The new first name of the user
  • [OPTIONAL] last_name: string. The new last name of the user
  • [OPTIONAL] password: string. The new password of the user
  • [OPTIONAL] email: string. The new email of the user Response

Data Storage/Modification

Data Retrieval

Data Deletion

Clone this wiki locally