Learning REST APIs in 15 Minutes

REST APIs are a way for programs to communicate with each other using URLs. It is an Application Programming Interface that follows the representational state transfer (REST or RESTful) software architectural style. A developer sets up an API on a server and allows clients to talk to it.

A practical example of this is when you go to YouTube to search for a funny cat video. When you write a search message and press enter, your browser sends a request to YouTube’s servers containing your search string. Their server processes that information and responds with a list of videos. The request and response model of communication is the core of the REST architecture. Because of their relative simplicity and versatility, REST APIs have become the de-facto way of transferring data on the internet.

Structure of a Request

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

Endpoints

A path parameter has the format https://api.github.com/users/{username}. When filled in, it will look like a unique endpoint, but the server will interpret part of the URL as a variable. For this endpoint, the parameter enclosed in curly brackets can be replaced by a username to get some information about that user, such as their name, number of repositories, and bio.

Query parameters allow you to send key-value items in your request URL. Unlike path parameters, they have a special syntax. They always begin with a question mark (?) and are separated by ampersands (&). An API endpoint with query parameters will look something like this: https://api.github.com/users/octocat/followers?page=1&per_page=1

Methods

  • 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

"Content-Type: application/json"

They have many applications, for example, they can be used to tell which type of data is sent in the request/response, so the receiver can know which parser to use. Other uses include request authentication, sending cookies, identifying clients, and more.

Body

Responses

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

Some common examples include 404: Not Found, 200: OK, and 500: Internal Server Error, at least one of these you have likely seen before, and now you know where it comes from.

Using an API

For our example, we will again use the GitHub API that has the root URL https://api.github.com. Let us use it to find some information about a user and then see how we can authorize our own account and create a new repository.

We will make the requests using the requests package in python. Because requests is not part of the python standard library, we must first install it:

$ pip install requests

We can use the requests.request function to make our request. Let us make a GET request to get some information about the octocat user, which is an account for Github's mascot. The request function has two mandatory arguments; The method to use and the URL to send the request to. On Github's API documentation https://docs.github.com/en/rest/reference/users we can find that there is an endpoint /users/{username} that provides public information about an account. Here is the code required to make the request:

response = requests.request(
"GET",
"https://api.github.com/users/octocat"
)
response.json()

When we run the code we get this output:

{
'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'
}

The response.json() method converted the response message into a dictionary for us and we can see that we get a good amount of information about this user.

We have talked briefly about how GET requests are considered safe, so we can use them without first authorizing ourselves. POST requests, on the other hand, have lasting effects on the server. Therefore, you must often authorize requests with other methods, to prove that you are permitted to perform the requested action. The most common way to authorize a request is to use headers.

For the GitHub API, you must first generate a personal access token to use as a unique identifier for your account that you can pass in the header. To do this, follow the steps outlined in this guide https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token. Make sure that the token has permissions to create a repository. Once finished, copy the token somewhere safe, as you will not be able to see it again. For this example, save your token as a constant TOKEN.

To find which endpoint we should use to create a repository, we once again refer to the documentation https://docs.github.com/en/rest/reference/repos#create-a-repository-for-the-authenticated-user, where we find the endpoint /user/repos that can have one or more body parameters, with name being required. We can make a new repository with a description with this request:

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}")

Here we use the JSON parameter of the request function, which converts a dictionary to JSON and adds the “Content-Type: application/json” header. We must also add an authorization header so that GitHub can know that we have permission to make this request. When we run the code, we get this:

Response: 201 - Created

We get a 200s response, which means that the request was successful.

Now you have seen what a REST API is and how requests and responses are structured. You have also seen how to consume an API using the requests client in python to make GET and POST requests. It is important to remember that a REST API is nothing more than an API that follows the REST architectural style. It is not set in stone, instead, it is up to each developer to follow the rules set by REST to the best of their ability. Therefore, it is important to read the documentation of the API you are going to use because no two APIs are the same.

The next step can be to create an API for your own application. Daeploy offers one of the easiest ways to convert your python code into REST API applications and deploy them as microservices. Click here to learn more and get started.

--

--

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 helps you to create APIs out of your existing #python code and deploy it as web services. Get started now!