REST API Basics - 4 Things you Need to Know

A REST API is the most common standard used between Clients (a person or application) who want to access information from the web from Servers (application or database) who have access to that information.

An Application Programming Interface (API) is a way for two computers to talk to each other over the web. For example, a delivery app can use the Google Maps API to support location tracking instead of building one from scratch. Or a recipe website can use an AI model to suggest alternative recipes based on the same ingredients using the ChatGPT REST API.

An API that follows the REST standard is called RESTful. Here are good practices when designing and using a RESTful API using the example of a survey app.

1. Basic format
2. HTTP verbs
3. URL endpoints
4. Status codes

1. Basic format

The format of a RESTful API has three main components: 1) URL endpoint; 2) HTTP verb; and 3) Body.

URL endpoint: Is a URL link that represents the resources we want to access. Resources can be text, images, documents or any data entry. For example, example.com/surveys allows us to view or create survey templates and example.com/surveys/123/responses allows us to do the same for all responses of survey 123.

HTTP verb: Tells the server what we want to do with the URL endpoint resource. For example, a POST request means we want to create a new survey template and a GET request means we want to view an existing survey template.

Body message: Is an optional custom payload which contains a message with the properties and values we want to use to create or update a given resource.

For example, we want to create a new response for the survey 123 which we captured which includes a positive NPS score of 9, a short feedback message and the unique id of the respondent who gave the feedback.

// Request:
POST example.com/surveys/123/responses

// Body payload:
{
  survey_id: 123, 
  nps_score: 9, 
  feedback: "love the service", 
  respondent_id: 42
}

The server receives the HTTP request and returns a response that includes a HTTP status code and a response usually in JSON format. Here is an example request and response to a REST API server asking to read all the responses for survey 123:

Request:

GET http://example.com/surveys/123/responses

Response:

// HTTP status code: 200
{
  survey_id: 123,
  survey_title: "nps onboarding survey",
  responses: [
  {
    response_id: 42,
    nps_score: 9,
    feedback: "love the service",
    respondent_id: 42
  }
  ...
 ]
}

2. HTTP verbs

There are 5 basic verb commands when making a HTTP request:

• GET: make a read only request to view either a single or list of multiple resources
• POST: create a new resource based on the payload given in the body of the request
• DELETE: destroy the given resource based on the id provided
• PUT: update the entire fields of the resource based on the given body of the request or create a new one if not already exist
• PATCH: update only the fields of the resource if it exists

Most applications and resources will support all these commands. This is commonly referred to as a CRUD application:

Acronym	HTTP verb
Create	POST
Read	GET
Update	PUT & PATCH
Delete	DELETE

3. URL endpoints

A URL endpoint in a RESTful API represents any given object, data or service the API can access. For example, example.com/surveys represents the data for all survey templates and example.com/surveys/123/responses the data for all responses of a given survey.

URL endpoints should be grouped as pluralised nouns around the business data and objects and not verbs. For example, example.com/surveys and not example.com/getAllSurveys.

URL endpoints should include the unique identifier as a path after the pluralised noun when viewing, updating or deleting a single item. For example, example.com/surveys/123.

Organise URL collections in a logical hierarchy based on relationships. For example, users are most likely to access responses to a given survey template. This would be represented as example.com/surveys/123/responses.

Here is a summary of good practice URL endpoints and how they interact with HTTP verbs:

URL endpoint resource	GET	POST	PUT	DELETE
/surveys	Retrieve all surveys	Create a new survey	Bulk update surveys (not advised)	Remove all surveys (not advised)
/surveys/123	Retrieve the details for survey 123	Error	Update the details of survey 123 if it exists	Remove survey 123
/surveys/123/responses	Retrieve all responses for survey 123	Create a new response for survey 123	Bulk update responses for survey 123 (not advised)	Remove all responses for survey 123 (not advised)
/responses/42	Retrieve the details for response 42	Error	Update the details of response 42 if it exists	Remove response 42

4. Status codes

Upon receiving a HTTP request in the basic RESTful format the server will return a HTTP status code along with any optional JSON payloads. Here are the most common HTTP status codes and their meaning:

Status code	Meaning
200 OK	Request was successful.
301 Moved Permanently	For SEO purposes when a page has been moved and all link equity should be passed through.
401 Unauthorized	Server requires authentication.
403 Forbidden	Client authenticated but does not have permissions to view resource.
404 Not Found	Page not found because no search results or may be out of stock.
500 Internal Server Error	Server side error. Usually due to bugs and exceptions thrown on the server side code.
503 Server Unavailable	Server side error. Usually due to a platform hosting, overload and maintenance issue.