Blog

Python API integration

Python Development

Python API integration

 

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 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 ccredentials, 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.

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.