Using Swagger documentation and Postman with the Ascribe APIs

The Ascribe APIs provide documentation both as static html pages and an interactive Swagger page.  The static documentation is more convenient for looking over the API, but the Swagger documentation provides powerful features for interaction with the API.  We will use examples from the Ascribe Coder API, but the same techniques apply to the Ascribe CXI API.

To open the documentation page for the API, navigate to the root URL of the API in your browser.  For the Ascribe Coder API this is https://webservices.goascribe.com/coder.  The top of the page looks like this:

Ascribe Coder API home page

Click the Documentation link in the toolbar to open the static help pages, or the Swagger link to open the Swagger documentation.  The top of the Swagger documentation page looks like this:

Swagger documentation toolbar

The REST resources available are laid out on the page like this:

REST resources

Two resources are shown here, Codebooks and Companies.  Each of these has one GET operation and one POST operation.  Click on the operation to show details.  For example, if we click the POST operation for the Companies resource we see:

Companies resource

The example response produced by Swagger is a bit confusing.  Swagger wraps the response example in an object that specifies the content type, in this case application/json.  The actual response body is the value of this property, or in this case:

{
  "key": 3,
  "id": "ACME"
}

This POST operation accepts parameters in the body of the request, as described in the Parameters section in the operation above.  To get details about the fields of the response or request bodies, click on the Model link above the example.  In this case for the Response body we see:

New Company Response

And for the Request body we find:

New Company Request

Experimenting with the API from the Swagger page

You can experiment with the API directly from the Swagger page.  To do so, the first step is to obtain a bearer token for authentication as detailed in this post.  To obtain the token, POST to the Session resource.  Expanding the POST operation of the Sessions resource we find:

Sessions resource

Click on the request example to copy it to the request body:

Sessions request body example

Now edit the values for the request body, providing your credentials.  I’ll log in to an Ascribe account called “Development”:

Sessions request body

Now click the Try it Out! button.  Scroll down to the Response Body section to find:

Sessions response body

The API has provided two tokens, either of which can be used for client interactions with the API.  You can elect to use either token, but don’t use both.  The tokens have different semantics.  The authenticationToken should be passed in a header with key authentication.  The bearer token should be passed in a header with key authorization.  The word bearer and the space following it should be included in the value of the authorization header.

The authentication token will remain valid for thirty minutes after the last request to the API using this token.  In other words, it will remain valid indefinitely provided you make a request with this token at least once every thirty minutes.  The bearer token never expires, but will become invalid if the account, username, or password used to obtain the token change.

The bearer token (but not the authentication token) can be used for experimentation with the API from the Swagger page.  To use the bearer token, copy it from the response body.  It is long, so it is easiest to copy the response body and paste it into a text document.  Then get rid of everything except the value of the bearer token.  This means everything within the quotation marks, including the word bearer, but not including the quotation marks.  You can save this value for future use so that you don’t have to go through this each time you experiment with the API.

Now, armed with your bearer token, paste it into the api_key box at the top of the Swagger documentation page:

Swagger API key

Now you are ready to work out with the API.  For example, you can expand the GET operation of the Companies resource and click Try it Out!  Assuming you have one or more companies in your account, you will get a response like:

{
  "companies": [
    {
      "key": 11288,
      "id": "Language Logic"
    },
    {
      "key": 11289,
      "id": "Saas-fee rentals"
    },
    {
      "key": 11291,
      "id": "ACME"
    }
  ],
  "errors": null
}

Using Postman

The Swagger documentation page is handy for simple experimentations, but you will probably want a better API development tool as you develop your own API client.  Postman is one such tool.  You can easily import the API from Ascribe into Postman.  To do so, open Postman and click the Import button in the toolbar:

Postman import

In the Import dialog, select Import from link.  Paste in the URL from the toolbar of the Ascribe Swagger documentation page:

Postman import from link

Click Import, and Postman will import the API like so:

Postman imported API

Adding the bearer token

That did a lot of work for you, but you still must tell Postman about your bearer token.  Edit the new Ascribe Coder API collection:

Postman edit collection

Select the Authorization tab and set the type to Bearer Token.  In the Token box, paste the value of the bearer token without the leading word bearer and the space following it:

Postman bearer token

Completing setup in Postman

Now you are ready to work out with the API in Postman.  Most of the operations are set up for you, but there are a few details to be aware of.

First, those operations that require a request body will not have that body properly populated.  You can either edit these by hand or copy the example body from the Swagger documentation into Postman as a starting point.

Second, be aware that Postman will create variables for operations that accept parameters in the request path and query string.  An example is the GET /Studies operation.  This operation accepts three parameters in the query portion of the url: idFilter, statusMask, and clientCompanyKey.  If we try this operation in Postman using initial configuration after importing the Coder API we get the response:

{
  "studies": [],
  "errors": null
}

Where are our studies?  You might expect to see all the studies for your account listed.  To understand why they are not listed, open the Postman console.  In the View menu in Postman, select Show Postman Console:

Show Postman console

Now, with the Postman console displayed, try the GET /Studies operation again.  In the Postman console we see:

Postman GET Studies default

This is the actual GET request URL sent to the API.  The request accepts three variables as parameters, and we have not supplied these variables.  We can tell Postman not to send these parameters by opening the Params section of the GET request in Postman:

Postman GET params

Clear the checkbox to the left of each of these parameters, then send the request again.  The Postman console now displays:

Postman GET Studies no parameters

and the response body contains a list of all studies on our account.  To query only for studies that are complete, set the statusMask parameter value to c:

Postman status mask

The console shows that the request now contains the desired status mask:

Postman console GET status mask

and the response body contains only those studies that are complete.

Using Swagger to Generate the API Client

The Swagger documentation can also be used to generate the initial code for your API client automatically.  Visit https://swagger.io/tools/swaggerhub/ for more information.  The code generation tools on this site can create API client code in a wide variety of languages and frameworks, including Python, Ruby, Java, and C#.

Summary

The Swagger documentation for Ascribe APIs does far more than simply documenting the API.  It can be used to create a test platform for API client development using Postman.  It can also be used to generate stub code for your API client.

Leave a Reply

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