What is API Documentation, and Why It Matters?

Automation has a crucial position in this technology-centric world. Faster and short releases are in vogue. In addition to that, the agile development method has gained a foothold in the software industry. There has been a remarkable change in the way we develop software automation tests in agile.

Rising Need For API Testing

The old practice of having only the GUI tests for automation does not exist anymore. Moreover, the problems in software testing with the GUI tests are several. To enumerate a few:

• The tests may fail frequently owing to frequent changes in the UI
• Additional maintenance and refactoring efforts associated with flaky tests
• Moreover, its a time-consuming test process and has slower feedback.
• It requires a large number of initiatives in terms of maintainability and stability.

In a two week aligned sprint, it gets altogether challenging to have a UI ready and test it simultaneously for test coverage results. Unlike the GUI tests, the API testing doesn’t rely on the UI. It becomes much more comfortable to conjoin/ integrate them under Agile Development. Additionally, it can be brought in much earlier at the development stage. The increasing/ rising trend of API Testing underlines this further.

An API abstracts the implementation layer, exposing only the objects needed by the developer. It consists of REST methods. Moreover, these REST methods fetch, manipulate, and delete the data in the application’s database. We need to familiarize ourselves with the workings of REST API basics. Please go through the REST API  tutorials to be acquainted with those. 

Once we have familiarised ourselves with the REST API basics, it is time to learn to test the REST APIs. To test a REST API, we must understand the interface of the API. This includes:

• The operations we can perform using the API
• Structure of the requests
• Structure of responses 

Therefore, an essential step in that direction would be to look at the API Documentations. In this article, we are going to cover:-

• Why do we need an API Documentation?
• What is an API Documentation?
• How to use API Document?
• What are the various types of tests for API?

Let us first understand the benefits of API Documentation.

Why do we need an API Documentation?

Documentation of any technology has a direct impact on the adoption and its usage. Without the knowledge of the tool, no one would know how to use it. Moreover, there are other advantages to it as listed below:

• It provides a quick and easy guide for API consumption.
• Reduces user frustrations.
• Demonstrates useful functions.
• Saves support costs and time.

These are some of the benefits of API documentation. Let us learn and understand what all consists of an API Documentation.

What is an API Documentation?

API documents are similar to a reference manual. It talks about the necessary information of an API, in terms of,

Description of Resources

The data returned by the API are resources. Various endpoints can be used to access resources. Under the same resource, an API will have several routes grouped. Resources and endpoint descriptions are generally short and precise. Additionally, the user guide contains a piece of more detailed information.

Methods and their endpoints

The endpoint is an essential part of the API documentation. The developers implement it to make the requests. Endpoints indicate ways to access resources. The methods indicate permissible interactions such as GET, PUT, POST, or DELETE with the resource. Endpoints, similar to overall resource descriptions, as well have short brief descriptions. The endpoint shows the end path of a resource. It does not include a common base path to all endpoints.

Consider a sample APIs collection available to us as TOOLSQA – Bookstore API provided by TOOLSQA. Please navigate to the URL. Consequently, once the page opens, we will see this:

In the above image:

Bookstore and Account are resources available in Bookstore API

An HTTP method acts as a verb. The listed verbs POST, GET, DELETE in the above image are some of the examples. Moreover, there are others as well, like PUT, PATCH, OPTION, etc.

The routes in the above image are:

1. /Account/v1/Authorized
2. /Account/v1/GenerateToken
3. /Account/v1/User
4. /Account/v1/User/{GUID}
5. /Account/v1/User/{UserId}
6. /BookStore/v1/Books
7. /BookStore/v1/Books

The routes are following the method to form an endpoint. Example, GET /Account/v1/Authorized.

Note: We have a very few endpoints listed here in the sample bookstore API URL. But in actual projects, the list of endpoints can be much large. 

For an endpoint, the full resource URL needn’t be listed in an API document. So, in our example, GET /Account/v1/Authorized is listed instead of GET  http://bookstore.toolsqa.com/Account/v1/Authorized

It is done with the thought to make the users focus on the path. Additionally, the user guide provides the full resource URL and the needed authorization in the introductory section. 

Parameters used

Parameters are the options that control the resource. There are four kinds of parameters:

1. Header parameter: As the name suggests, these are the parameters passed into the request headers. They are generally related to the authorization and included under a separate section of authorization requirements for standard header parameters. Additionally, in the case of unique parameters passed in the headers, they are documented with the respective endpoint. 
2. Path parameter: Path parameters are part of the endpoint. They are not optional. We usually write them along with curly braces. For example,  /Account/v1/User/{UserId}  Here, {UserId} is the path parameter. 
3. Query parameter: They are attached to the URL end. Additionally, the Query Parameter is appended to the URL after adding ‘?‘ at the end of the URL. You can read more in the Query Parameter tutorial. 
4. Request body parameters: In a POST request, several times, a JSON object is submitted in the request body. Moreover, it is a list of key-value pairs.

Example:

Examples of Requests and Responses

In the above example, we passed the username and password as request body parameters. We got a 200 status code response along with the response body for the POST request of the endpoint /Account/v1/GenerateToken, we sent.

Alongside, if you notice the highlighted section, it is that of a curl command.

We follow Curl format for several reasons:

• Firstly, curl is independent of the programming language.
• Secondly, it consists of the request header information.
• Additionally, it displays the Request method.

Thus, we have understood the contents of a typical API document. An API document may contain additional information. But the above part of the tutorial gives us a general idea of everything included under an API document. Subsequently, in our next stage, we will learn the usage of an API document.

How to use an API Document?

To understand the use of Swagger API documentation, we will use the same Bookstore API used previously. It consists of a sandbox environment that tests the APIs on the documentation. 

Navigate to the Bookstore API. You will see the following:

The grouping of endpoints is as follows:

• Account
• BookStore

Some of those API Endpoints listed below build our End to End Rest API Framework. Please try these examples once you have learned to use the API document at the end of this section.

HTTP VERB	Route	PURPOSE
POST	/Account/v1/GenerateToken	To generate token as the endpoint name suggests
GET	/Account/v1/User	To create a userId with associated user
GET	/BookStore/v1/Books	To fetch a list of books
POST	/BookStore/v1/Books	To add a book associated with the user
DELETE	/BookStore/v1/Books	To remove a book
GET	/Account/v1/User/{UserId}	To get a list of books associated with userId

We listed some of the APIs below from the bookstore API. They will help us to understand the requests and their response bodies using Swagger.

1. To Create User
2. To Generate Token with the created User

API Documentation – Create User – POST

Before we begin exploring the APIs, we need to create a user with a username and password. Subsequently, add a desired username and password under Book Store Credentials.

Note: Please choose your username and password, and once created, remember to use the same username and password for all the tests. For example, throughout we will be using TOOLSQA-Test as username and Test@@123 as password.

Now, let’s try and create a userID using the POST  Request for User.

Make a request

1. First, Expand the POST method for the endpoint under Account: /Account/v1/User
2. Second, click the Try it out button. The Request Body field gets editable.
3. Third, add the username and password. You have added now, as indicated in the below screenshot. After that, select the parameter content type as application/json. Click on the Execute button.
4. Finally, Swagger submits the request. It shows the curl that was submitted. The Response, for the request, is observed in the response section.

Note: Please note down the userID. You will need it for other APIs in the request body. 

Explanation:  We passed a POST Request with username and password in JSON format. We got a 201 status code along with userID, and books associated with the respective username in the Response body. It explains that our request was successfully sent over the server, as you can see in the above image under Description. Additionally, Swagger’s implementation is simple and useful. It provides an interactive experience to send a request and receive a response for APIs.

As software professionals, we need to understand the underpinnings on which great software builds. One of the many means is to try and test them over in various ways. We familiarized ourselves with the API Documentation. Additionally, Swagger provided us with the means to test it on Swagger UI itself.

API Documentation – Generate Token – POST

Now that we have created a user in our previous response let’s try and create a token using the POST  Request for User.

Explanation:  We sent our request with the body containing a username and password in the application/json format. When we click the Execute button, we got a 200 status code. Additionally, we also got a response body with the token, expires, status, and result fields. In the next section, we will understand the context of API tests and study its various types.

What are the various types of API Tests?

Before we commence actual testing of the APIs, we need to compile associated information of the APIs. The context in which we carry out testing is essential because it drives our testing efforts.

Below is a non-comprehensive list of the information we can seek before we start testing the APIs:

• Expected response code from a successful request
• Expected response code from an unsuccessful request
• Fields to be validated
• Parameters required
• Error handling of unsuccessful requests
• HTTP verbs that we can use with the endpoints

Let us understand, under which all categories the API tests can be divided. It is not to say that we have enlisted a comprehensive list; there could be more types we can add to the list. But more or less, the API tests fall under one of the categories mentioned below.

1. Validation Testing: It forms one of the last segments in the software development process. It caters to the testing explicitly done to assess the product; its behavior, and its efficiency. The API is examined for correctness in implementation as per the expectations. Additionally, the API is also verified based on pre-established agreed-upon criteria such as the delivery of specific end goals, integration with the specified environment. In addition to that, the testing of API’s behavior to access the correct data happens as a part of Validation testing.
2. Functional Testing: This is one of the broader types of testing. It aims to test specified functions. While testing the APIs for functional testing, the assessment of the responses received happens against expected responses in terms of passing parameters. Additionally, the error handling for unsuccessful requests and invalid responses too are under consideration under these tests. The boundary cases, along with regular tests, fall under the scope of these tests.
3. UI Testing: UI Tests tend to be more specific. These tests assess the user interface against the APIs and their constituent parts. Additionally, the tests are more generalized with a focus on the API health; it’s usability as well as compatibility of the front end and back end.
4. Load Testing: This test is for the functionality and performance of the APIs under load. The API undergoes theoretical regular traffic. The test results form the baseline to conduct further load testing. Additionally, the testing also includes subjecting the API to maximum possible traffic to test the behavior of the API under full loads. APIs undergo overloading tests. In this test, the verification of the API performance and error handling conditions during failure happens.
5. Error Detection: The tests for APIs, which include the monitoring, inducing execution errors, sending invalid requests, detecting operational leaks, etc. fall under this category.  The introduction of known failure scenarios in the APIs happens. The testing of these APIs happens to ensure that the errors are detected, handled as well as routed.
6. API Security tests: Specific tests verify the APIs performance for vulnerabilities from external threats. Security testing, Penetration testing, and Fuzz testing are some of them. For example, Security testing involves validation of the APIs in terms of security requirements. Additionally, these security requirements could be related to permissions, authorizations, authentications, etc.  An authorized attack launches against the system as a part of Penetration testing. It evaluates the security of the API. A full-scale assessment report of strengths and weaknesses of the APIs is the deliverable issued after such a test. In Fuzz testing, evaluation of API behavior happens. It is subjected to unexpected, invalid, and random data of enormous size. Following this, the crashes, built-in assertions, and memory leaks are known.
7. Integration testing: The Integration tests focus on API communication with another module APIs.
8. Reliability testing: The API should display a prompt response for different configurations. It also looks for a response data structure as a part of testing.

To conclude, in this post, we have got an understanding of API documentation. We learned to use the Swagger API document. Additionally, we acquainted ourselves with types of API testing.

In further posts, we will learn to build REST API Automation Framework around the API tests. Try out using the API document as guided above and reach out for your valuable feedback.