Writing tests for RESTful APIs in Python using requests – part 1: basic tests

Recently, I’ve delivered my first ever three day ‘Python for testers’ training course. One of the topics that was covered in this course is writing tests for RESTful APIs using the Python requests library and the pytest unit testing framework.

In this short series of blog posts, I want to explore the Python requests library and how it can be used for writing tests for RESTful APIs. This first blog post is all about getting started and writing our first tests against a sample REST API.

Getting started
To get started, first we need a recent installation of the Python interpreter, which can be downloaded here. We then need to create a new project in our IDE (I use PyCharm, but any decent IDE works) and install the requests library. The easiest way to do this is using pip, the Python package manager:

 pip install -U requests 

Don’t forget to create and activate a virtual environment if you prefer that setup. We’ll also need a unit testing framework to provide us with a test runner, an assertion library and some basic reporting functionality. I prefer pytest, but requests works equally well with other Python unit testing frameworks.

 pip install -U pytest 

Then, all we need to do to get started is to create a new Python file and import the requests library using

import requests

Our API under test
For the examples in this blog post, I’ll be using the Zippopotam.us REST API. This API takes a country code and a zip code and returns location data associated with that country and zip code. For example, a GET request to http://api.zippopotam.us/us/90210

returns an HTTP status code 200 and the following JSON response body:

     "post code": "90210",
     "country": "United States",
     "country abbreviation": "US",
     "places": [
             "place name": "Beverly Hills",
             "longitude": "-118.4065",
             "state": "California",
             "state abbreviation": "CA",
             "latitude": "34.0901"

A first test using requests and pytest
As a first test, let’s use the requests library to invoke the API endpoint above and write an assertion that checks that the HTTP status code equals 200:

def test_get_locations_for_us_90210_check_status_code_equals_200():
     response = requests.get("http://api.zippopotam.us/us/90210")
     assert response.status_code == 200

What’s happening here? In the first line of the test, we call the get() method in the requests library to perform an HTTP GET call to the specified endpoint, and we store the entire response in a variable called response. We then extract the status_code property from the response object and write an assertion, using the pytest assert keyword, that checks that the status code is equal to 200, as expected.

That’s all there is to a first, and admittedly very basic, test against our API. Let’s run this test and see what happens. I prefer to do this from the command line, because that’s also how we will run the tests once they’re part of an automated build pipeline. We can do so by calling pytest and telling it where to look for test files. Using the sample project referenced at the end of this blog post, and assuming we’re in the project root folder, calling

 pytest tests\01_basic_tests.py 

results in the following console output:

Console output showing a passing test.

It looks like our test is passing. Since I never trust a test I haven’t seen fail (and neither should you), let’s change the expected HTTP status code from 200 to 201 and see what happens:

Console output showing a failing test.

That makes our test fail, as you can see. It looks like we’re good to go with this one.

Extending our test suite
Typically, we’ll be interested in things other than the response HTTP status code, too. For example, let’s check if the value of the response content type header correctly identifies that the response body is in JSON format:

def test_get_locations_for_us_90210_check_content_type_equals_json():
     response = requests.get("http://api.zippopotam.us/us/90210")
     assert response.headers['Content-Type'] == "application/json"

In the response object, the headers are available as a dictionary (a list of key-value pairs) headers, which makes extracting the value for a specific header a matter of supplying the right key (the header name) to obtain its value. We can then assert on its value using a pytest assertion and the expected value of ‘application/json‘.

How about checking the value of a response body element? Let’s first check that the response body element country (see the sample JSON response above) is equal to United States:

def test_get_locations_for_us_90210_check_country_equals_united_states():
     response = requests.get("http://api.zippopotam.us/us/90210")
     response_body = response.json()
     assert response_body["country"] == "United States"

The requests library comes with a built-in JSON decoder, which we can use to extract the response body from the response object and turn it into a proper JSON object. It is invoked using the json() method, which will raise a ValueError if there is no response body at all, as well as when the response is not valid JSON.

When we have decoded the response body into a JSON object, we can access elements in the body by referring to their name, in this case country.

To extract and assert on the value of the place name for the first place in the list of places, for example, we can do something similar:

def test_get_locations_for_us_90210_check_city_equals_beverly_hills():
     response = requests.get("http://api.zippopotam.us/us/90210")
     response_body = response.json()
     assert response_body["places"][0]["place name"] == "Beverly Hills"

As a final example, let’s check that the list of places returned by the API contains exactly one entry:

def test_get_locations_for_us_90210_check_one_place_is_returned():
     response = requests.get("http://api.zippopotam.us/us/90210")
     response_body = response.json()
     assert len(response_body["places"]) == 1

This, too, is straightforward after we’ve converted the response body to JSON. The len() method that is built into Python returns the length of a list, in this case the list of items that is the value of the places element in the JSON document returned by the API.

In the next blog post, we’re going to explore creating data driven tests using pytest and requests.

Using the examples for yourself
The code examples I have used in this blog post can be found on my GitHub page. If you download the project and (given you have installed Python properly) run

 pip install -r requirements.txt 

from the root of the python-requests project to install the required libraries, you should be able to run the tests for yourself. See you next time!

19 thoughts on “Writing tests for RESTful APIs in Python using requests – part 1: basic tests

  1. This is Cool stuff. Helped me preparing for my interview

    Added my code practice here:

    Filename: apitest.py
    import requests
    import json
    import pytest

    Sample response
    “post code”: “90210”,
    “country”: “United States”,
    “country abbreviation”: “US”,
    “places”: [
    “place name”: “Beverly Hills”,
    “longitude”: “-118.4065”,
    “state”: “California”,
    “state abbreviation”: “CA”,
    “latitude”: “34.0901”

    def api_response():
    url = ‘http://api.zippopotam.us/us/90210’
    response = requests.get(url)
    return response

    def api_response_body_json(api_response):
    # print(api_response.json())
    return api_response.json()

    def test_status_code(api_response):
    print(“status_code of response is:” + str(api_response.status_code))
    assert 200 == api_response.status_code

    def test_zipcode(api_response_body_json):
    zip_code = api_response_body_json[“post code”]
    print(“Zipcode value is:” + zip_code)
    assert 90210 == int(zip_code)

    def test_place_name(api_response_body_json):
    place_name = api_response_body_json[“places”][0][“place name”]
    print(“Zipcode value is:” + place_name)
    assert ‘Beverly Hills’ == place_name

  2. Hi Bas. Thanks for sharing this. Very simple and straight forward. I liked your approach. Instead of writing many words, you simply represented it using practical examples. Easy to understand. Thanks!

  3. Hi sir, I want to know how can I run pytest api test over gitlab ci? Currently I am learning pytest to test rest api, I can just run pytest of python file to test but not usre how to automate the process by using gitlab ci. Appreciate if you can advise or show some step example. Thank you sir.

    • Yes, that can be done. You’ll need to create a .gitlab-ci.yml file that contains the command line instruction to run the tests.

      Examples and documentation here: https://docs.gitlab.com/ee/ci/examples/

      It might be a good idea to write a blog post that shows how to create a GitLab pipeline that checks out the code from GitHub, runs those tests and shows the reports, indeed. I don’t have one ready at the moment but I’ll make a note.

      • Thank you. I really hope you can post tutorial of this. I look forward your post related. Thank you sir. Thanks for sharing and your advise.

  4. Hi Bas,

    I came across this post today, I was looking for some simple testing method for business user. Asking to test in postman will be too much for them. I am going to try this.

    Thanks for sharing this post!

  5. Hi Bas,

    Thanks for such a nice article, I am able to test my APIs with the help of this tutorial.
    Suggest some ways and tools also for better reporting / e-mailing of the test results.
    I have used pytest-html but that gives very basic structure.


    • Hey Aman, I haven’t really looked into reporting frameworks for Python yet. I’ll try and let you if I ever stumble upon something that might be useful.

  6. That’s cool, but out of curiosity, how do you recommend testing your own webserver? The way these tests are written using ‘requests’ assume the server is up.

    While another way to test the server would be to test the various routes, using the corresponding fn that implement them (e.g. in flask).

    The reason I am asking is that in deployment settings, for instance heroku, you typically run the tests before you deploy the app.

    • Hey Vignesh, there are a couple of follow up blog posts that deal with sending payload as part of a POST request, PUT would be the same I guess.

  7. This tutorial describes a functional test. It would be interesting to see a post on testing a unit code of the REST API and measure its coverage.

    Thanks anyways. 🙂

    • You’re welcome! Might be something to work on in the future, but it would probably not use requests as a library and therefore wouldn’t fit this series..

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.