This is the post I wish I could have read before I approached my first API. All APIs have their own style, quirks and unique requirements. This post explains general terminology, tips and examples if you’re looking to tackle your first API.

Here’s what is covered:

1. API & HTTP Lingo You Should Know
2. Testing and Exporting Python Request Code from Postman (Optional)
3. Formatting Your Request
4. Example GET and POST Requests
5. “Gotchyas” To Avoid & Conclusion

Terminology Clarification: I will refer to “items” or “data” throughout this post. This could be substituted for contacts or whatever data you are looking for. For example, you might be fetching a page of contacts from your CRM. Or fetching your tweets from Twitter’s API. Or searching the Google location API, you might look up an address and return geo-location coordinates.

API & HTTP Lingo You Should Know

Hypertext Transfer Protocol (HTTP)

Per Mozilla,”Hypertext Transfer Protocol (HTTP) is an application-layer protocol for transmitting hypermedia documents, such as HTML. It was designed for communication between web browsers and web servers, but it can also be used for other purposes. HTTP follows a classical client-server model, with a client opening a connection to make a request, then waiting until it receives a response.”

HTTP: you = client. API = way to communicate with server

Application Programming Interface (API)

Per Wikipedia, the purpose of an API is to simplify “programming by abstracting the underlying implementation and only exposing objects or actions the developer needs.”

Representational State Transfer (REST)

REST is an architectural style of web APIs. It is the dominant architecture that many APIs use. Simple Object Access Protocol (SOAP) is another style I’ve heard of, but it seems less common nowadays.

A REST API is built for interoperability and has properties like: “simplicity of a uniform interface” and “visibility of communication between components by service agents.” [Wikipedia] If an API follows REST, it has many good principles baked in.

GET, POST and PATCH

These are three common types of request methods.

• GET:  Read data returned, such as all of your tweets in the Twitter API.
• POST: Create a new item, like writing a new tweet. Can also update existing data. (Tweets aren’t editable though!)
• PATCH: Similar to POST, this is typically used for updating data.

URL or “endpoint”

The website location to send your request

URL Parameters

Values you pass to tell the API what you want. They are defined by the API specifications, which are usually well documented. In python’s requests library, they are passed as keyword arguments. Sometimes they are passable directly within the endpoint url string.

Body or “payload”

To make a request, you send a payload to the url. Often this is a JSON string or “object” with your parameters and values, AKA the request body. If the API is written specifically for Python, it might accept an actual Python dictionary.

Javascript Object Notation (JSON)

JSON is the data interchange standard for all languages. Usually it is the default way to pass data into and receive data from an API. If making a  POST, you can check your json object is formatted correctly by using a json linter. See also: Python 101 – An Intro to Working with JSON

Headers

These usually contain website cookies and authorization info. They also may tell the API what kind of data you want back. JSON and XML are the two most common types of data to return. You can specify the return format in the content-type headers.

If you need to parse an XML response, check out Python’s stock ElementTree API. I’ve only seen a few APIs using XML responses, such as the USPS Address Validation API.

Authorization

Authorization varies widely. This is the level of identification you need to pass to the API to make a request. Public APIs might require none. Some just need a username and password. Others use the Oauth standard, which is a system involving credentials and tokens for extra security.

Pages

API data is commonly returned in multiple pages when there is a lot of data returned. Each page can be accessed one request at a time. Sometimes you can specify how many items you want on a page. But there is usually a maximum items per page limit like 100.

Status code

Each request usually gives you a numeric code corresponding to happened when the server tried to handle your request. There is also usually a message returned.

See also: Web Server Gateway Interface (WSGI)

“As described in PEP3333, the Python Web Server Gateway Interface (WSGI) is a way to make sure that web servers and python web applications can talk to each other.”  Gunicorn is one of a few Python WSGI clients. web2py is another WSGI client and web framework I have used.

See also: Nginx

See Also: Create, read, update and delete (CRUD)

Creating the Request JSON

I recommend using Postman in most cases, depending on the complexity of the API. If the JSON syntax is straightforward, you can format your data as a python dictionary, then convert it to a JSON object with json.dumps from the standard library’s json module. But JSON can be tricky sometimes. You may also need to pass a dictionary of HTTP headers.

Some APIs have “Postman Collections”, a set of Python (or any language) script templates for the API. In those cases, it might make sense to use those resources.

Path One: Make HTTP request with json & requests libraries

Format Python dict with json.dumps from the standard library’s json module.  Infer API requirements from documentation. Use requests for HTTP.

Path Two: Make HTTP request with Postman & requests library

Use Postman to generate the JSON payload. Plug headers and payload into requests. Use requests library for HTTP.

Postman has a friendly interface for plugging in all your pieces and tinkering with your request body until it works. Make it easier on yourself and use Postman, especially if there are collections. An alternative is to troubleshoot in Python if you are confident in your grasp of the API. I use both options depending on my familiarity with the API at hand.

Once you have the request working, you may export your Postman request to almost any language. For Python, you can sometimes export to the requests,  http.client or urllib libraries. Hit the “code” button in Postman and then copy your code.

Python Installation

You can install requests with pip. Alternatively, http.client is included with in the python standard library. If you want to convert a request to a dataframe, install pandas.

If you choose not to use Postman, you can use the json library. See the use of json.dumps()to convert a dictionary to a JSON object in Example #2 below

Formatting Your Request

1. Paste your Postman headers, payload and url into your existing code.
2. You’ll likely need to use string formatting to pass values to your request body’s parameters or url.
3. If the API uses a token or other form of authorization that need to be refreshed intermittently, you’ll want to set up a way to fetch a token and feed it to your headers. In those cases, I usually have a function named fetch_token() that returns a token. Then I pass it to my requests.get or requests.request function. You’re now ready to test the request.

Example #1: GET the geolocation details of any public location with the Google API

This was modified from another example of Google’s Geolocation API. To use this, you need to create a developer account with Google and paste your API keys below.

import requests
# import pandas as pd

"""find a great burger spot in Leon, MX!"""
payload = {"key":"Add_Google_API_Key_Here", "address":"Capitan Mosistaza"}
response = requests.get(url="https://maps.googleapis.com/maps/api/geocode/json", 
                        params=payload)
print(response.text)
print(response.status_code)
data = response.json()

# extracting latitude, longitude and formatted address of the first matching location
latitude = data['results'][0]['geometry']['location']['lat']
longitude = data['results'][0]['geometry']['location']['lng']
formatted_address = data['results'][0]['formatted_address']
print(longitude)
print(latitude)
print(formatted_address)

# optional: convert response into a dataframe with pandas 
# location_table = pd.json_normalize(data['results'])
# location_df = pd.DataFrame.from_dict(location_table)
# location_df.to_csv('Locations.csv')

Above you can see:

• requests makes it easy to see the server’s text response also with response.text
• requests also makes JSON encoding easy with response.json()
• I like to use pd.json_normalize() to convert the response object to a dataframe.

Example #2: Encode a Python dictionary to json string and POST to a hypothetical API

1. Create a simple dictionary with request body data.
2. Convert it to encoded json string with json.dumps from the standard library’s json module.
3. POST the encoded JSON to the endpoint url with requests.

import json
import requests
def convert_dict_to_json_object():
    """Create request body with fictional contact details."""
    payload = {
        "first_name":"P",
        "last_name":"Sherman",
        "address":"42 Wallaby Way",
        "address_2":"",
        "city":"Sydney",
        "state":"NSW",
        "country":"AU",
        "zip":"2000"
        }
    print(type(payload))
    json_obj = json.dumps(payload, ensure_ascii=True)
    print(type(json_obj))
    return json_obj

def create_new_contact(json_obj):
    """
    This is a fictional API request. 
    Passing a json object to requests.
    Decoding server response with response.json(), 
    Returning a contact id by calling the data's keys.
    """
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "cache-control": "no-cache",
        "Postman-Token": f"{postman_token}"
        }
    response = requests.request(method="POST", 
                                url="https://SomeSoftwareAPI.com/contacts/", 
                                data=json_obj, 
                                headers=headers)
    data = response.json()
    print(data.keys())
    contact_id = data['contact_id'] # Call decoded JSON keys to get the return values.
    return contact_id

json_object = convert_dict_to_json_object()
contact_id = create_new_contact(json_object)

“Gotchyas” To Avoid

• Status codes are your friend. They offer a hint at why your request is not working. If you see 200 or 201, that’s a good sign. They’re usually helpful, but sometimes they can be misleading.
• Ensure you are defining the correct content-type. I had an experience where Postman defined two conflicting content-type headers and it caused my request to fail. The server’s error message indicated the problem was in my JSON, so it took me a while to figure out the headers were the problem.
• Sometimes it makes a difference if your url has http:// vs. https:// in it. Usually https:// is preferred.

Conclusion

I remember APIs seemed mysterious and daunting before I had used them. But like all things, they can be conquered with knowledge, understanding and tenacity to keep trying until you figure it out. Hope this helps you slay your dragon. Good luck!

Requests Documentation

requests.request() API documentation

requests.get() API documentation

requests.post() API documentation

Supplementary Reading

Google’s HTTP Timing Explanation

List of Interesting “Unofficial” APIs

Proxy servers