Write a RESTful API Integration in Python

These days, it becomes popular to use web APIs to connect to the cloud, integrate a particular service inside your application, or automating a process based on information from another platform. Essentially, API is everywhere! But how can we use an API by ourselves?

Read the Docs!

Before jumping into code, we have to understand how we should interact with the API. Let’s read the docs!

General Details

In case we need to choose an API from a bunch of services, it might be a good idea to check the following:

  1. Pricing: you should check the API pricing before jumping into the API docs. There might be better free APIs, while there might be a good paid API.
  2. Rate Limit: the number of requests you can send at an amount of time. There may be another API with a higher rate limit, in case you need more requests per second.

Authentication

The way you prove you are some user, to obtain the relevant data or accomplish an action.

  1. Cookie: several APIs also support using a cookie for authentication. Usually, the cookie appears in the Cookie header.
  2. API token: usually, tokens are generated by the user inside a configuration page. Some APIs may add roles/permissions to the API token so that the token will not be accessible to all service’s resources. Every API specifies how to pass the token. For example, it could be as a query parameter in the URL, inside the Authorization header with custom type, a custom-header, etc.
  3. OAuth: OAuth is an authorization protocol, mainly for an application to obtain access to a web service, using authorization flows. There are two versions of the protocol (1.0 and 2.0). OAuth 2.0 is a complete rewrite of OAuth 1.0 from the ground up. OAuth 1.0 is deprecated right now (or at least should be deprecated), although some services still support it, like Twitter.

Let’s Develop!

To make it simple, we will see how to create an integration through an example. In our case, we will use the GitHub REST API. We want to obtain all details about the public repositories of the authenticated user.

Step 1: Using requests

requests is an elegant Python library for executing HTTP requests.

  • url
  • params: the query string parameters (the parameters in the URL).
  • data / json: the body of the HTTP request.
  • headers: for the HTTP request.
  • auth: auth tuple to enable Basic / Digest / custom HTTP authentication.
  • Many more! The full list.

Step 2: Code Improvements

Let’s improve our code! We can notice multiple problems:

  • The authentication is invalid.
  • The data is invalid (for example, the visibility is a random string).

Step 3: Writing a client

We can write a class representing an API client. This class should store the unique data of the client, such as the credentials, essential headers, and more. Now, we can create multiple clients!

  • headers: should be used at every request.

Step 4: Improving the client

We can improve the client’s implementation!

Step 5: Writing a generic client

In case you have to develop multiple clients, such as a client for each service of your product, you should consider writing a generic REST client. Thus, you make sure you don’t implement the HTTP logic multiple times.

Summary

Writing a good API integration is not that hard, but takes time for understanding the best solution for your situation. Writing a client object might be an overhead sometimes, whereas it may save time in the future.

  • Validation: add validation for your parameters, such as a validation for the base URL in the REST client, as well as the credentials in the GitHub client. Moreover, consider adding a method for testing the API before actually using it.
  • Tests: like every piece of software you develop, you want to ensure the client behaves properly.

Passionate about creating stuff.

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