How to Integrate API with Python

The majority of production Python web applications rely on several externally hosted application programming interfaces (APIs). APIs are also commonly referred to as third-party services or external platforms. Examples include Twilio for messaging and voice services, Stripe for payment processing, and Disqus for embedded webpage comments. 

There are many articles about proper Python API design, but best practices for integrating APIs are less commonly written about. However, this subject continuously grows in importance because APIs provide critical functionality across many implementation areas. 

What is an API? 

A Web API is a way for web applications to communicate with each other. APIs are  present and used in every major web service. Python APIs consist of two entities: a client and the  server, the former requesting something and the latter responding to the request. 

An API consists of endpoints, which are the connection points for data and services. To communicate with the Python API, the client issues a request to an endpoint, to which the server responds with a specifically structured response message. The most common ways to pass data to and from an API are using JSON or XML formats. There are multiple Python API protocols, the most popular being REST and SOAP. Python APIs are most commonly operated on using one of the most common operating methods: creation, update, read, and deletion, usually abbreviated as  CRUD. These methods correspond to what actually is happening with the data on the server and, in general, to the user interface elements – for example, search functionality falls under the  “read” operation. Clients use HTTP request methods to communicate the request, which includes GET (read), POST and PUT (creation), PATCH (update), and DELETE (deletion)  methods, among some others. 

The resources, also called endpoints, are most commonly thematically grouped and provide easily understandable names. Resources can be a singletone or a collection. For  example, endpoints, responsible for user profile actions and interactions, should all be grouped  under /users collection, in which there can be multiple singletones (e.g. /users/profile or /users/search) or sub-collections (e.g. /users/profile/edit and /users/profile/comments etc.). 

Python APIs can be limited based on access level and usage into three categories: private,  partner (customer), or public (open). APIs can also be categorized into data and service APIs.  Data APIs expose and allow operations on internal data; service Python APIs provide additional functionality, usually embedded third-party service provides. 

Private python APIs are designed for internal use, mainly to enable communication between client-side and server-side logic. An example of a private python API would be the authorization service of your web application and endpoints, used to exchange data between a user interface and server. It is also really common to use private APIs to check for updates in the background without forcing the user to refresh the page. 

Twilio, a service provider most known for its SMS and phone call capabilities is a perfect example of a partner API – they offer their services on a subscription basis. Another common way of granting access to partner APIs, which most payment processors use, is to charge a fee upon using a certain endpoint. 

Public python APIs are usually made to process external data or allow access to internal data,  like movie details and search functionality or weather-related information.  

When to create an API 

The question should be when to create public or partner python APIs – private APIs are usually built during the initial development of the application. The first thing to implement when creating an externally accessible python  API is to implement an API-specific authentication flow that allows easy access to endpoints. 

Basic API infrastructure should be implemented as soon as possible to allow for easy scaling when new functionality is being introduced. It is generally recommended to develop an  API according to a set of universal rules, which most commonly is OpenAPI Specification. 

Existing API can be extended as soon as a new feature set has been implemented to allow access to related functionality.

What Users Want in an API 

The user base of an API will depend on what the python API is and will predominantly consist of developers who rely on the API in some way – be it internal or external usage. A good python API, designed for external use, provides documentation for each of the endpoints to let developers and users know what kind of data to send in and what sort of response to expect. The endpoint documentation usually consists of information about allowed  HTTP request methods, required level of access, what inbound and outbound data is supposed to be – this information is in most cases sufficient for potential users to implement a connection. 

APIs need to be reliable, well-maintained, and supported. It is generally recommended to gradually add automatic test coverage to your python API to allow for easier maintenance. 

It is strongly preferred for python APIs to be versioned according to the changes that are being introduced to allow for backward compatibility since any newly released features or changes of already existing endpoints can break the existing functionality. Introducing tests would also help with this issue.

API Status Codes

Status codes are returned with every request that is made to a web server. Status codes indicate information about what happened with a request. Here are some codes that are relevant to GET requests:

• 200 Everything went okay, and the result has been returned (if any).
• 301 The server is redirecting you to a different endpoint. This can happen when a company switches domain names, or an endpoint name is changed.
• 400 The server thinks you made a bad request. This can happen when you don’t send along the right data, among other things.
• 401 The server thinks you’re not authenticated. Many APIs require login credentials, so this happens when you don’t send the right credentials to access an API.
• 403 The resource you’re trying to access is forbidden: you don’t have the right permissions to see it.
• 404 The resource you tried to access wasn’t found on the server.
• 503 The server is not ready to handle the request.

You might notice that all of the status codes that begin with a ‘4’ indicate some sort of error. The first number of status codes indicate their categorization. This is useful — you can know that if your status code starts with a ‘2’ it was successful and if it starts with a ‘4’ or ‘5’ there was an error. 

How to use an API with Python 

1. Using Python API as client 

It is quite important to understand that Python, despite mostly being focused on the server-side APIs, can also be used to implement client-side API connections. 

There are a multitude of ways to make a request to an external API using Python, the most popular of them being the requests library. It is sufficient in most cases where API  connection only uses an endpoint or two. In cases where it is planned to use external python API  extensively, it may be worth looking into implementing a custom library that would handle most of the background functionality like authorization and data serialization. 

We recommend considering doing the same thing to developers who are building an API  – if you are expecting a substantial amount of developers using your python  API, you should implement a custom library. It’s also a good idea to implement a Python library for the private API to help other developers in your team. 

In most cases, a web application will be using many external python APIs of all kinds – it is quite common too, for example, using Auth0 for authentication, AWS DynamoDB for data storage,  Stripe for payment processing, etc. All of these services are communicated using an API  connection. 

Most major web services provide libraries, which are a way to abstract from directly communicating with the python API by instead opting into using predefined connection methods written in the Python programming language. For example, Amazon Web Services have a Python library boto3, which helps Python developers use their service and allows them to not be dependent on version changes, as AWS is well known for having a complicated, highly versioned API. Most of the larger payment processors usually have their own libraries, but some of the smaller (or local to your country) might only have an API available. 

2. Using Python API as the server 

More common usage of APIs in Python is their implementation in Python-based web applications. Most major Python web-focused frameworks like Django and Flask offer built-in tools to implement basic python APIs.Extensions to these tools extend their functionality tremendously,  the most known of them being the Django REST Framework. It takes care of most of the background requests and data processing, after which, in most cases, only some configuration and adjustments will be made. It also provides experienced developers with the ability to override and reconfigure most of the options to their liking. Such frameworks usually additionally provide better python API security. 

Like the somewhat new but growing in popularity FastAPI, some frameworks are mainly focused on implementing Python APIs and provide great tooling like the automatic documentation generation (usually using Swagger UI). Automatically generated python  API  documentation can be achieved for most Python web frameworks using various Python libraries like the extensions for the aforementioned Swagger, ReDoc or Sphynx. 

Using an API-focused framework or library (like the Django Rest Framework, which is a  well-known API-focused extension for Django) usually means implementing a private API for the separately implemented frontend – usually written in one of the more popular JavaScript frameworks, like Vue or React. 

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

The code looks fine right now. Yet, we can improve it more! 

Logging: consider adding logging when executing an HTTP request. Also, log when some error occurs. It will save time when an error occurs in your application that uses the client. Validation: add validation for your parameters, such as a validation for the base URL in the REST client and 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.

Conclusion

There are a million other things you can learn about APIs: different headers, different content types, different authentication techniques, and so on. However, the concepts and techniques you learned in this tutorial will allow you to practice with any API of your liking and to use Python for any API consumption needs you may have. 

Case Studies