Working with APIs using Python

I love automation and believe automating repetitive tasks makes the world a better place as it would free up humans to work on more interesting challenges! APIs are one of the most useful tools in setting up automation so I thought I'd take some time to write about them and share my experience using them.

Let's start by defining the word 'Program'. 'Program' can be used as a noun or a verb, in the noun form, it means a set of instructions provided to a computer to perform a certain task while in the verb form it means to provide a human/computer a set of instructions to perform a task automatically.

Figure 1: API/Program Illustration

API stands for Application Programming Interface and it is a way for humans and programs to interact with programs. Here's a simple illustration of how an API works:

Figure 2: API Analogy

What this means is that the application has some endpoint that you can reach (such as an HTTP GET request to a particular website endpoint) that causes the application to provide you with the data that you request.

Types of APIs:

1. Open APIs -> These are also known as public APIs or external APIs. These are APIs that are available for everyone to use, they might be restricted by security measures.
2. Partner APIs -> These are APIs that are only available based on business agreements with stronger security measures restricting access.
3. Internal APIs -> These are APIs that are used within a business for development/business-related functions and are not open to public users.
4. Composite APIs -> These combine multiply APIs to bundle calls or requests and receive one unified response from different servers.

Common API architectures:

An API architecture is a development guideline/list of rules that the API development needs to adhere to.

1. SOAP APIs -> Simple Object Access Protocol. Client and server exchange messages using XML.
2. RPC APIs -> Remote Procedure Calls. Can use XML or JSON.
3. Websocket APIs -> Modern API development that uses JSON objects to pass data.
4. REST APIs -> Representational State Transfer. Most popular & flexible APIs. Use JSON as well.

REST APIs:

REST APIs are those that adhere to 6 architectural guidelines:

1. Client-Server architecture: The Client and the Server have to be independent allowing improvements to be made more granularly to either the client or the server-side.
2. Statelessness: There must be no session information stored on the server side and each client request must be independent of the other.
3. Cacheability: There needs to be clear demarcation from the server-side whether the data being transmitted can be cached and if so for how long. Useful for internet-scale applications.
4. Layered system: This allows the client to access the server in the same way irrespective of whether there is a load balancer or any other system between the client and the server serving the end-point.
5. Code-on-demand: The ability to send executable code from the server to the client when requested, this allows the server to add functionality to the client that it normally doesn't have for some specified period of time.
6. Uniform interface: This has the following 4 parts.
1. Resource identification in requests.
2. Resource manipulation through representations.
3. Self-descriptive messages.
4. Hypermedia as the engine of application state.

APIs that work across networks are called 'web APIs'. Web APIs that adhere to REST architectural constraints are called RESTful APIs.

Working with REST APIs:

Figure 3: REST API

The following are the 4 HTTP methods that can be used:

1. GET
2. POST
3. PUT
4. DELETE

Some basic HTTP codes to help us interpret:

Figure 4: HTTP status codes

Working with APIs using Python:

The module that we will be using is the 'requests' module. We can install it from the "cheese shop" using the following command:

'$ python -m pip install requests' or just 'pip install requests'

The following is the python code for a simple GET request:

>>> import requests

>>> requests.get("https://randomuser.me/api/")

<Response [200]>

We can store the response object in a variable ('foo') and get all the information we need from it. We can see the content of the response by using the '.text' method. The requests module will try to automatically decode the content from the server (e.g. UTF-8). We can change this by setting r.encoding = "ISO-8859-1" or to some other format.

>>> r = requests.get ("https://api.github.com/events")

>>> r.text

It is easy to pass parameters in the URL as well.

>>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']}

>>> r = requests.get('https://httpbin.org/get', params=payload)

>>> print(r.url)

https://httpbin.org/get?key1=value1&key2=value2&key2=value3

* Some of the common errors & exceptions are 'ConnectionError' in case of a network issue, 'Timeout' in case of a timeout, and 'TooManyRedirects' if the request exceeds an allowed number of redirects.

---

Further reading: 

[1] APIs for Dummies - https://www.ibm.com/downloads/cas/GJ5QVQ7X

[2] Web API Design - https://cloud.google.com/files/apigee/apigee-web-api-design-the-missing-link-ebook.pdf

---

References:

[1] WiKi pages -> https://en.wikipedia.org/wiki/API & https://en.wikipedia.org/wiki/Representational_state_transfer

[2] AWS Whitepaper -> https://aws.amazon.com/what-is/api/

[3] Realpython site -> https://realpython.com/python-api/

[4] Hubspot -> https://realpython.com/python-api/
[5] Requests module docs -> https://requests.readthedocs.io/en/latest/