Understanding APIs and How to Test Them

API (an abbreviation of Application Programming Interface) is a special interface (a set of commands/controls) that is designed for the interaction of different programs with each other.

The programs themselves can be written in any programming language, work locally or remotely, on their own server, or in cloud infrastructure, no matter what.

The main thing is that through the API they can "understand" each other and interact: exchange data, transmit/receive commands for execution, etc. But in order for the API to be clear to both parties, they need to discuss a single communication format (protocol) in advance. That is why the API is documented in detail so that developers of other programs external to your interface can take into account the format of your data and requests when designing their software.

API Types

Local API - Allows components of the same program to interact with each other
Remote API - Link multiple systems together. The Remote API includes SOAP and REST.

The API always appears before the GUI. Accordingly, we can start testing at an early stage, for example, when the API is ready, but the GUI is not. You can also often find that the API is a contract between services.

How it works

Methods of calling:

GET - The GET method is used to get any information identified by the Request URI. If the Request URI refers to the process issuing the data, the response will be the data generated by this process, and not the code of the process itself (unless it is the output data of the process). The GET method changes to "conditional GET" if the request message includes an "If-Modified-Since" header field. In response to a conditional GET, the body of the requested resource is transmitted only if it has changed after the date specified in the "If-Modified-Since" header.

The algorithm for determining this includes the following cases: If the status code of the response to the request is different from "200 OK", or the date specified in the "If-Modified-Since" header field is incorrect, the response will be identical to the response to a normal GET request. If the resource has changed after the specified date, the response will also be identical to the response to a normal GET request. If the resource has not changed after the specified date, the server will return the status code "304 Not Modified". The use of the conditional GET method is aimed at unloading the network since it allows you not to transmit redundant information over the network.
POST - The POST method is used to request the server to accept the information included in the request as subordinate to the resource specified in the Status Line in the Request URI field. The POST method was designed to be able to use one common method for the following functions: Annotation of existing resources Adding messages to newsgroups, mailing lists or similar groups of articles Delivering data blocks to processes processing data Expanding databases through the addition operation.

The real function performed by the POST method is determined by the server and usually depends on the URI Request. The added information is considered subordinate to the specified URI in the same sense as the file is subordinate to the directory in which it is located, the new article is subordinate to the newsgroup to which it is added, and the record is subordinate to the database.
The client can offer a URI to identify a new resource by including the "URI" header in the request. However, the server should consider this URI only as a tip and can save the request body under a different URI or without it at all. If a new resource was created as a result of processing the POST request, the response must have a status code equal to "201 Created" and contain the URI of the new resource.
PUT - The PUT method requests the server to save the Request Body under a URI equal to the Request URI. If the Request URI refers to an already existing resource, the Request Body should be treated as a modified version of this resource. If the resource referenced by the Request URI does not exist, and this URI can be considered as a description for a new resource, the server can create a resource with this URI. If a new resource has been created, the server must inform the client who sent the request through a response with the status code "201 Created". If an existing resource has been modified, a "200 OK" response should be sent to inform the client about the successful completion of the operation. If a resource with the specified URI cannot be created or modified, an appropriate error message should be sent.

The fundamental difference between the POST and PUT methods is the different value of the URI Request field. For the POST method, this URI specifies a resource that will manage the information contained in the request body as an appendage. A resource can be a data-processing process, a gateway to some other protocol, or a separate resource that allows annotations. In contrast, the URI for the PUT request identifies the information contained in the Content of the Request.
The user of the PUT request knows exactly which URI he is going to use, and the recipient of the request should not try to apply this request to any other resource
PATCH - partial data update method
DELETE - The DELETE method is used to delete resources identified by a URI Request. The results of this method on the server can be changed by human intervention (or in some other way). In principle, the client can never be sure that the deletion operation has been performed, even if the status code transmitted by the server informs about the successful execution of the action. However, the server should not inform about the success until, at the time of the response, it is going to erase this resource or move it to some unreachable area.
COPY - data duplication method.
HEAD - The HEAD method is similar to the GET method, except that the server does not return the Response Body in the response. The meta information contained in the HTTP headers of the response to the HEAD request must be identical to the information of the HTTP headers of the response to the GET request. This method can be used to obtain meta-information about a resource without transmitting the resource itself over the network. The "Conditional HEAD" method, similar to the conditional GET, is not defined.
OPTIONS - the method is used to describe the parameters of the connection to the target resource
LINK - The LINK method establishes relationships between the existing resource specified in the Request URI and other existing resources. The difference between the LINK method and other methods that allow the establishment of links between documents is that the LINK method does not allow you to pass the Request Body in the request and that as a result of this method, new resources are not created.
UNLINK - The UNLINK method removes one or more reference relationships for the resource specified in the Request URI. These relationships can be established using the LINK method or some other method that supports the "Link" header. Deleting a link to a resource does not mean that the resource ceases to exist or becomes unavailable for future links.
PURGE - the method, although it is not defined in the HTTP RFC (which allows custom methods outside of standard defined methods). Some HTTP servers and caching systems actually implement PURGE
TRACE - the method calls the returned test message from the resource.
LOCK and UNLOCK - The Lock and Unlock methods are used to create a global critical section when it is necessary to ensure synchronization of scripts running in separate threads. The Lock method opens the critical section, the Unlock method closes it.
PROPFIND - Using the PROPFIND method, you can request: the amount of occupied/free disk space (according to RFC 4331); a list of files and subdirectories contained in the directory (with the header Depth: 1); other properties of the file or directory.

Services communicate with each other through the methods that I described above. Let's look at the examples below to see what the request and the response of the services look like.

Input data

HTTP Request

GET / HTTP/1.1
Host: test.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; rv:18.0) Gecko/20100101 Firefox/18.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US;q=0.5,en;q=0.3
Accept-Encoding: gzip, deflate
Cookie: wp-settings
Connection: keep-alive

Output data

HTTP Response

HTTP/1.1 200 OK
Date: Sun, 10 Feb 2013 03:51:41 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=5
Server: Apache
X-Pingback: //webkyrs.info/xmlrpc.php
 
<!DOCTYPE html PUBLIC «-//W3C//DTD XHTML 1.0 Transitional//EN»>
<html xmlns=»http://www.test.com/xhtml»>
<head>
<meta http-equiv=»Content-Type» content=»text/html; charset=utf-8″ />
<title>Test Name</title>
</head>
<body>
</body>
</html>

HTTP response codes

The server can send different codes in response to user requests. These can be error codes or just codes informing users about the status of the server. The most well-known codes are 4xx (client-side problems) and 5xx (server-side problems).

REST API

This is the ideology of API construction, which stands for Representative State Transfer API. It is based on the following principles formulated by its creator, Roy Fielding:

Client-server architecture

Stateless server
Cachability
Multi-layer structure
Unified interface
Code on demand

Authentication

Usually, to use the API, you need a special key with which the server recognizes the user. In open APIs, the key may be missing or provided upon request (for example, after registration on the site).

The OAuth authentication protocol is widely used to integrate services with each other

Briefly about how to test the API

Of course, there are some specifics here, but we can use such generally accepted techniques as:

Analysis of boundary values. Parameter values can be passed explicitly in API requests. This is a great reason to highlight the boundaries of input and output values and check them.
The division into equivalence classes. Even a small API has many use cases and many combinations of input and output variables. Therefore, we can once again use our skills of allocating equivalent classes.

It seems to me that when testing, you need to take into account that APIs are created largely for the integration of services. And it is often not people who work with them, but other software systems. Therefore, it is necessary to evaluate the API from the point of view of its usability with other products, from the position of easy integration with it. A self-respecting API should also have clear and detailed documentation.

It can be concluded that all types of testing that we are used to - functional testing, load testing, security testing, usability testing, documentation testing - are not alien to API testing. In principle, this is not surprising, because the API is a full-fledged independent product.

Tools for working with the API

Regular GET requests can be sent using the browser. But there are many special tools that are designed for API development and testing. They provide an opportunity not only to send various types of requests but also to save requests, show results in various formats and act as a proxy server. And much much more.

Among such tools are:

Postman. An application that allows you to send requests, record them, show history and much more. Convenient and understandable.
jMeter. A tool that has gained fame primarily due to the load testing that can be carried out with its help. But this is just one of its many uses.
Charles. Allows you to view sent HTTP requests. And a lot more.
SoapUI. A powerful product for developing and testing web applications. I haven't used it myself, but I've heard a lot of reviews - both good and bad.
Advanced REST Client. Another extension for Chrome to work with the API (query design, display them in a convenient way, and more).