Learning REST APIs in 15 Minutes

Structure of a Request

A REST API request consists of four components

  1. An endpoint
  2. A method
  3. Headers
  4. A body

Endpoints

Every API will have a root URL, for example, https://api.github.com/ for Github's public API. An endpoint is an addition to the root URL where the server accepts requests. For the GitHub API, there is a /users endpoint that responds with a list of users. When added to the root URL to form the full path we get https://api.github.com/users. Try opening that URL in a browser and you will see that you get a response as raw JSON. In addition to pointing to certain functionality of the server, endpoints can also be used to send parameters. There are two ways to do this, path parameters and query parameters.

Methods

Most APIs use HTTP methods to communicate which type of functionality the request will have. The endpoint can have one or more methods. Each method implies which type of behavior the request will have, but it is up to the API developers to follow these rules. The methods themselves do not have any inherent behavior. In total, there are nine HTTP methods, but four of them are much more common than the rest, so we will focus on these. They are:

  • GET: Used to request data from the server. GET methods should have no additional effect on the system.
  • POST: Used to add new data to the server. Often causing a change in state or side effects.
  • PUT: Used to update data on the server.
  • DELETE: Used to request the deletion of a resource on the server

Headers

Headers are a way to pass additional data with an API call. A header consists of a key and a value, separated by a colon (:). For example:

"Content-Type: application/json"

Body

The last component of a request is the body, which contains the data of the request. A body is typically required by POST and PUT methods, for example, to store or update a database entry. Request bodies can contain many different types of data, such as JSON, HTML or binary files. It is common practice to use the “Content-Type” header to denote which kind of data is being sent in the body.

Responses

When a server receives a request, it will process it and return a response. A response has headers and a body, just like a request does. But it also has a status code, that says what happened with the request. The status codes range from 100+ to 500+. Each status code has its own meaning, and they are grouped such that the first number in each status code has a special meaning.

  • 100s: Informational responses
  • 200s: Successful responses
  • 300s: Redirection responses
  • 400s: Client error responses
  • 500s: Server error responses

Using an API

Now that you know what a request and response look like, let us use of this knowledge to make some requests to a public API. To make requests, you will need an HTTP Client. Luckily, they are available in most programming languages. Some common ones are curl in bash, requests in python, and AJAX in JavaScript.

$ pip install requests
response = requests.request(
"GET",
"https://api.github.com/users/octocat"
)
response.json()
{
'login': 'octocat',
'id': 583231,
'node_id': 'MDQ6VXNlcjU4MzIzMQ==',
'avatar_url': 'https://avatars.githubusercontent.com/u/583231?v=4',
'gravatar_id': '',
'url': 'https://api.github.com/users/octocat',
...'followers': 3714,
'following': 9,
'created_at': '2011-01-25T18:44:36Z',
'updated_at': '2021-04-22T14:27:39Z'
}
response = requests.request(
"POST",
"https://api.github.com/user/repos",
json={
"name": "rest-api-tutorial",
"description": "This repository was created as part of a tutorial on REST APIs"
},
headers={"Authorization": f"token {TOKEN}"},
)
print(f"Response: {response.status_code} - {response.reason}")
Response: 201 - Created

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
daeploy

daeploy

10 Followers

Daeploy helps you to create APIs out of your existing #python code and deploy it as web services. Get started now!