This article was originally written as part of the BobaBoard documentation.
APIs allow applications (clients) to interact with another application (server) without unfettered access to the underlying data, or to the whole set of operations that can be executed on it. In short, an API is a contract defined by the server that establishes a common language that clients can use to communicate with it. Most operations allowed by APIs boil down to fetching, storing or updating data.
While there are no enforced rules about how APIs should be defined, BobaServer's API implements a special set of API guidelines called REST. Among the advantages of adhering to REST principles, is that REST APIs are easier to reason about, define, and scale. You can read about the REST principles followed by BobaServer in the API guidelines page.
How a REST API works
REST APIs rely on the HTTP protocol, the same browsers use to navigate most webpages. In particular, a REST API defines a set of endpoints
(URLs) that the client can access to execute operations. A REST API also defines the semantic of the data the client will send to describe the operation parameters, as well as the one of the data it will receive in response.
For requests, REST APIs rely on HTTP methods
to execute different operations on the same resource using a single endpoint
associated with it. For responses, REST APIs rely on HTTP Status Codes
to communicate the result of the operation.
Additional data required as part of the request or response is referred to as the request/response payload
. BobaBoard's API returns responses in the JSON format
.
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.
Here are some operations that might be available to the client:
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 achieve this, the client sends a GET
request to the /threads/thread_456/contributions/contribution_123
endpoint.
Possible responses include:
- An HTTP Status Code of
200
with apayload
that contains the contribution data. - An HTTP Status Code of
404
if the contribution does not exist. - An HTTP Status Code of
401
if the access requires authentication data and none was found in the request.
GET
requests are the default type of request the browser sends when you access a web page.
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 achieve this, the client sends a POST
request to the /threads/thread_456/contributions/contribution_123
endpoint. The POST
request would also include the contribution data as a payload
.
In practice, the contribution id would likely be determined by the server when creating the contribution. In this case, the
POST
request would be sent to the/threads/thread_456/contributions/
endpoint instead, and the assigned contribution id would be returned as part of the responsepayload
.
Possible responses include:
- An HTTP Status Code of
201
if the contribution was successfully created. This might include apayload
that contains the finalized contribution data. - An HTTP Status Code of
401
if creating the contribution requires authentication data and none was found in the request. - An HTTP Status Code of
409
if a contribution with the given id already exists.
POST
requests are most often used by browsers when submitting forms.
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 achieve this, the client sends a PUT
request to the /threads/thread_456/contributions/contribution_123
endpoint. The PUT
request would also include the updated contribution data as a payload
.
Possible responses include:
- An HTTP Status Code of
201
if the contribution was successfully created. This might include apayload
that contains the finalized contribution data. - An HTTP Status Code of
403
if the user is not authorized to update the contribution. - An HTTP Status Code of
404
if the contribution does not exist.
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 achieve this, the client sends a DELETE
request to the /threads/thread_456/contributions/contribution_123
endpoint.
Possible responses include:
- An HTTP Status Code of
204
if the contribution was successfully deleted. - An HTTP Status Code of
403
if the user is not authorized to delete the contribution. - An HTTP Status Code of
404
if the contribution does not exist.
If this article was useful, consider retweeting it!
Top comments (0)