API Testing with HTTPie
By: Martin Thoma
Tags: QA, Programming, Software Development, Quality Assurance, Testing

The Basics

What is an API?

When a website is created for human users, it has a graphical interface. People parse websites visually, looking for common design elements such as headers, navigation, the content section, maybe some metadata.

When we build something for other developers, we call it API: Application Programming Interface. It is purely text-based and has a more formal structure. Imagine it like specified forms. The API has documentation that formally states “if you send me form X, I will respond with form Y”.

Client / Server and Request / Response

In the API world, we have a client and a server. The client is typically a browser and the server is where the website/content is. Typically, there are lots of clients and only very few servers. A server is both, the hardware and the software. It depends on the context.

The client and the server have a request/response relationship. In this example, the client sends a GET request for the “/a/life” resource. The server responds with the status code 200 (SUCCESS) and other headers. The payload is {“answer”: “42”}. Image by Martin Thoma.

The client sends a request to the server. The server sends a response back.

HTTP Methods

Each request uses exactly one HTTP method. The five most common methods are:

GET : A GET request should never change anything. You just want to read what is there

: A GET request should never change anything. You just want to read what is there POST : Create something new.

: Create something new. PATCH : Update an existing object.

: Update an existing object. PUT : Similar to POST and PATCH combined. The client sends an identifier. If that identifier exists, update the object behind it. If not, create the object.

: Similar to POST and PATCH combined. The client sends an identifier. If that identifier exists, update the object behind it. If not, create the object. DELETE: Remove an object.

So you can say: “The client sends a GET request.”.

Trivia: When you just enter a URL in your browser, the browser will always send a GET request. When you fill out a form on a website, it is typically a POST request.

Headers and Payload

Requests and responses consist of arbitrary many headers and the payload. The headers are key-value pairs, e.g.

Access-Control-Allow-Methods: GET

Access-Control-Allow-Origin: *

Connection: keep-alive

Content-Length: 66

Content-Type: application/json; charset=utf-8

Date: Thu, 19 Aug 2021 16:35:15 GMT

ETag: W/"42-LkrMrL9tE0cI3pye0CURr5DjFK4"

Server: nginx/1.16.1

X-Rate-Limit-Limit: 1000

X-Rate-Limit-Remaining: 999

X-Rate-Reset: 26685

The payload can be anything. Typically text, but it could also be a byte-stream. In the case of REST APIs, the text is typically JSON formatted:

{

"count": 165452,

"gender": "male",

"name": "peter",

"probability": 0.99

}

HTTP Status Codes

There are 3 status codes you should know:

200: Success — Everything worked fine.

404: Not Found — you or the developers messed up

500: Internal Server Error — the developers messed up

They always have 3 digits and they are grouped by the first digit:

1XX: Information

2XX: Success codes

3XX: Redirects

4XX: The server thinks that the client did something wrong

5XX: Something went wrong on the server

Good resources to look up specific codes are: