Swagger Documentation

The OpenAPI (formerly known as Swagger) Specification defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. The IEDB NG Tools API includes a OpenAPI interface for our API endpoints to help users understand and interact with the service.

Usage

From the UI, API request methods (GET, POST, PUT, DELETE) are displayed for each endpoint. It is then followed by the actual endpoint and a brief description of it.

Let’s take the following GET request for an example:

Once it’s selected, it should display the description of the request, parameters, and responses. For this example, the descriptions tells us that this request should provide us with description/accepted parameters for Cluster. It also shows that there are no parameters required to run this request.

Now, let’s click Execute.

The Response section should be updated.

Starting from the top, it shows the curl command that was used to execute this request, and the request URL.

Curl and Request URL

The Response body can be retrieved through running the curl command on the terminal, or pasting the Request URL to the browser.

It is then followed by the server response (body, headers, and duration). We can see that the response body shows a json result showing all parameters of Cluster.

Request with Parameters

Some endpoints will take parameters to complete the request. Let’s take a look at the allele search endpoint.

This endpoint shows that it can take four parameters (query, limit, toolsname, and predictor).

The textboxes are initially disabled. Select Try it out to enable the textboxes, and fill the textboxes with the following vlaues.

• query: 0201

• limit: 5

• toolsname: mhci

• predictor: netmhcpan

The expected output is a list top 5 alleles available in NetMHCpan that has the closest match to the query 0201.

Let’s run this request by selecting Execute.

In the Response body, you will see 5 alleles that matches closest to 0201.