REST API Basics - 4 Things you Need to Know (2024)

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:

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:

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: