Post navigation

Get your swagger on!

That was then…

Enterprise Tester ships with a REST API, which has been growing ever since its introduction in version 4.3.

The API allows you to write programs which directly interact with the Enterprise Tester server, allowing you to configure, insert, update and query information from the Enterprise Tester server without needing to access the UI. Enterprise Tester’s API is growing with every release – and version 4.8 ships with 268 unique operations!

Prior to 4.8 of Enterprise Tester, the API has shipped with detailed documentation, but the shape of requests and responses has only been documented partially in examples.

The problem with “documentation by examples” is that if we haven’t provided an example of using a particular field, property or parameter -then there is no way for you to know it exists without experimenting through the API itself.

Introducing Swagger

Swagger is a specification for documenting the REST API and APIs which are documented, using the swagger specification, and provide vital information about how the REST API works, in what ways you can interact with it, and what data you can expect to get back from it.

The Swagger specification is simple and takes a pragmatic approach to representing an API – it does not endeavour to support representing every possible REST API there is, but the subset it does support is simple and easy to understand. This is where it differs from other service description technologies such as WSDL, WADL or WADL2.

Swagger declares things such as parameters, basic input validation, URL paths and the models you can expect to use with the API.

The neat thing about Swagger is that it is detailed enough so you can generate client-code for the API based purely on the details held within the swagger for the API and the specification is simple enough that writing a client generator is something you could complete in an afternoons work – as opposed to a week!

Within this document is details of every api (resource) and operation (HTTP Method) supported by the API. You can find more details about the Swagger specification here on the Swagger core specification wiki.

How can this help me?

With the introduction of Swagger has two big advantages:

Richer documentation for the API.

The ability to generate your own API client, making it easy to start using the ET API.

Lets take a look at the richer documentation first.

Swagger UI

Enterprise Tester now ships with “Swagger UI” – Swagger UI can take the Swagger API description for the ET API and automatically generate documentation that’s both easy to read, detailed and interactive!

To get to the Swagger UI that ships with ET v4.8 and above, access the in-app help by clicking on the “User” button in the top-right of the browser, then selecting “Help”. Once in the help, navigate to API -> Features -> Swagger.

From here you will see the Swagger help topic, including a link to launch the Swagger UI, which will look something like this:

When you click on it, you will be taken to a new tab that will include a list of all the supported operations.

For each operation you can click on it, to see the details – lets take a look at the GET /api/projects method (project list).

At the top we can see the HTTP method (GET), the path (/api/projects) as well as a list of supported expansions, the Swagger nickname (more on this later) and the Response class – which is the shape/schema for the data that will be returned as the response to this request.

If we scroll down to the bottom we can then see a set of text boxes (representing the parameters of the request) and a button “Try it out!” – so let’s click the button.

Immediately you will see some new content appear, this is the request and response returned when we tried the API out against the local server.

If we wanted to try out the method with an expand – we can do that too:

Notice the expand parameter is added to the Request URL, and if we scroll down we can see that the project’s priorities list is in-lined as part of the response.

Now that we’ve had a look at Swagger UI – let’s next take a look at generating our own client.

Swagger Client Generation

Writing client code for REST API’s can be very tedious – and also error-prone. Taking the hassle out of writing client code by hand is one of Swagger’s primary use-cases, and one we very much had in mind when introducing support for Swagger into Enterprise Tester.

There are a number of Swagger client generators available – including ones for Javascript and through a tool called Swagger code-gen support for Java, Ruby, PHP, Python etc.

For Enterprise Tester we have included an example of generating a .Net client for Enterprise Tester, which is created from Swagger for the API, and features very little code – showing just how easy this can be.

If you recall in the earlier Swagger UI section, we saw the swagger Nickname under the section “Implementation Notes” – nicknames used to generate method names for our client. So for example, to add a new project to Enterprise Tester via the generated C# client is simply:

Where “createProject” was the nickname given to the POST method of the /projects resource.

We are really excited by the possibilities Swagger brings – making our API easier to consume and use from different languages, and helping your team get up to speed with interacting with Enterprise Tester via its powerful API.

More to Come

In version 4.8 we have introduced Swagger support, and have implemented support for generating clients in C# – but this is only just the beginning. Over the coming versions of Enterprise Tester we are looking to make further improvements to our Swagger output, including:

Better descriptions, and more details for each resource and operation.

Better support for some more unusual operations (such as mixed-entity-type search results and aggregation queries).

We strongly encourage you to take the time to look at the Swagger UI and the generated C# client. We would love to hear your feedback on how we can make our API, API Documentation and API educational resources even better.