Skip to content
BobaBoard Docs

Introduction to APIs

Application Programming Interfaces (APIs) allow applications (clients) to request data or actions from other applications (servers), without being given full access to all the data and actions that exists on those servers.

In short, a server’s API defines the language (“contract”) that client applications must use to communicate with it. Most API operations involve fetching, storing, or updating data.

While there are very few restrictions on how APIs can be defined, boba-backend’s API follows a special set of API guidelines called REST. REST APIs allow clients to communicate with a server by “visting” addresses (URLs) that represent specific resources, similar to how browsers access different web pages through their addresses.

Following REST principles has several advantages, including easier understanding, definition, and scalability of APIs. You can find more details about the REST principles followed by boba-backend in the API guidelines page.

How a REST API works

Section titled “How a REST API works”

REST APIs use the HTTP protocol, which is the same protocol web browsers use to navigate websites. Specifically, a REST API defines a set of URLs called ‘endpoints’ that a client (your application) can “visit” to perform operations or request data.

A REST API also specifies the format of the data the client needs to send for the operation and the format of the data it will receive in response.

When a client makes a request to a REST API, it uses different HTTP methods to perform specific operations on the resource associated with an endpoint. When the server responds to a request, it uses HTTP Status Codes to indicate whether the operation was successful and its result, if any.

Any additional data that needs to be sent or received as part of the request or response is referred to as the request/response payload. In the case of BobaBoard’s API, the responses are returned in the JSON format.

REST API example

Section titled “REST API example”

As an example, let’s define the REST API endpoint that associated with contributions on a thread. This endpoint will live at the /threads/:thread_id/contributions/:contribution_id address, and support the following operations:

  • GET: fetch the contribution data
  • POST: create a new contribution
  • PUT: update the contribution
  • DELETE: delete the contribution

Remember that endpoints often accept only a subset of these operations. Make sure to check the documentation of the APIs you’re using before sending requests!

GET: Fetch the data for a contribution in a thread

Section titled “GET: Fetch the data for a contribution in a thread”

The client wants to fetch the contribution with id contribution_123 in the thread with id thread_456.

To do this, the client sends the following request:

  • Endpoint: /threads/thread_456/contributions/contribution_123
  • HTTP Method: GET

Possible responses include:

  • Success (ok): An HTTP Status Code of 200 with a payload that contains the contribution data.
  • Not found: An HTTP Status Code of 404 if the contribution does not exist.
  • Authentication needed: An HTTP Status Code of 401 if the access requires authentication data and none was found in the request.

POST: Create a new contribution in a thread

Section titled “POST: Create a new contribution in a thread”

The client wants to create a contribution with id contribution_123 in the thread with id thread_456.

To do this, the client sends the following request:

  • Endpoint: /threads/thread_456/contributions/contribution_123
  • HTTP Method: POST
  • Payload: The content of the contribution in the format specified by the server.

Possible responses include:

  • Success (created): An HTTP Status Code of 201 if the contribution was successfully created. This might include a payload that contains the finalized contribution data.
  • Authentication needed: An HTTP Status Code of 401 if creating the contribution requires authentication data and none was found in the request.
  • Conflict: An HTTP Status Code of 409 if a contribution with the given id already exists.

PUT: Update a contribution in a thread

Section titled “PUT: Update a contribution in a thread”

The client wants to update a contribution with id contribution_123 in the thread with id thread_456.

To do this, the client sends the following request:

  • Endpoint: /threads/thread_456/contributions/contribution_123
  • HTTP Method: PUT
  • Payload: The content of the updated contribution in the format specified by the server.

Possible responses include:

  • Success: An HTTP Status Code of 201 if the contribution was successfully updated. This might include a payload that contains the finalized contribution data.
  • Authentication needed: An HTTP Status Code of 401 if updating the contribution requires authentication data and none was found in the request.
  • Invalid authentication: An HTTP Status Code of 403 if the authenticated user is not authorized to update the contribution.
  • Not found: An HTTP Status Code of 404 if the contribution does not exist.

DELETE: Delete a contribution in a thread

Section titled “DELETE: Delete a contribution in a thread”

The client wants to delete a contribution with id contribution_123 in the thread with id thread_456.

To do this, the client sends the following request:

  • Endpoint: /threads/thread_456/contributions/contribution_123
  • HTTP Method: DELETE
  • Payload: None

Possible responses include:

  • Success (no content): An HTTP Status Code of 204 if the contribution was successfully deleted.
  • Invalid authentication: An HTTP Status Code of 403 if the user is not authorized to delete the contribution.
  • Not found: An HTTP Status Code of 404 if the contribution does not exist.