Accessing the iKnow REST APIs in 2017.1

This earlier article already announced the new iKnow REST APIs that are included in the 2017.1 release, but since then we've added extensive documentation for those APIs through the OpenAPI Specification (aka Swagger), which you'll find in the current 2017.1 release candidate. Without wanting to repeat much detail on how the APIs are organised, this article will show you how you can consult that elaborate documentation easily with Swagger-UI, an open source utility that reads OpenAPI specs and uses it to generate a very helpful GUI on top of your API.

Installing Swagger-UI

Swagger-UI is a lightweight web application that you can easily run as a static web page locally after downloading the github repo, without any recompiling or building required. Alternatively, you can find the guidelines to launch it with Docker on the same page. But if you're as lazy as I am (or was, the first time round, to be precise!), you can even skip the downloading part and leverage Swagger's online demo at http://petstore.swagger.io:

As Swagger-UI is running entirely locally, you can simply paste the URL to your OpenAPI Specification in the input field at the top and press "explore". The (local) Swagger-UI JavaScript code will then fetch that specification and turn it into a fancy GUI like the one for their demo petstore app pictured above.

The URL for our iKnow REST API's OpenAPI Specification is http://localhost:57772/api/iKnow/v1/samples/swagger, changing the localhost, 57772 and samples pieces for whichever host, port and namespace are appropriate in your situation. It's a good idea to try that URL in your browser separately in order to verify there's no nosy security settings preventing you from direct access. For example, if you have anything but minimal security configured for your system, you'll have to authenticate in order to be able to reach that URL. To authenticate, you can either append ?CacheUserName=_SYSTEM&CachePassword=SYS to your URL (fine for local tests, not for production, of course!), or supply an authentication token. You should then see the OpenAPI Spec in YAML style:

swagger: '2.0'

info:
  version: "1.0.0"
  title: iKnow REST APIs
  description: |
    This is the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) 
    of the iKnow REST APIs, giving you RESTful access to iKnow domain contents in your system
    Use [swagger-ui](https://github.com/swagger-api/swagger-ui/blob/master/README.md)
    or a similar tool to conveniently browse and test these APIs.
    For more information on iKnow, visit [intersystems.com](http://www.intersystems.com)

  contact:
    name: InterSystems
    url: http://wrc.intersystems.com
    email: support@intersystems.com

consumes:
  - application/json
produces:
  - application/json
...

This YAML code may not be the most exciting prose to read on your backpacking break, but it is enough for Swagger-UI to understand what this whole API is about and automatically generate a nice GUI to work with it. Barring slight version differences, it should look like this:

Accessing the API

Now that you have Swagger-UI running, let's take a closer look at the generated GUI and how you can use it to test requests and responses to and from the REST APIs for use in your application. For example, expand the "Miscellaneous" header to see a few simple API methods, such as consulting the list of domains in your namespace and then click the GET operation /domains. As this operation doesn't take any parameters, you can hit the "Try it out" button straight away.

If you're running this in the SAMPLES namespace and have set up the Aviation Demo domain with ##class(Aviation.Utils).SetupStandalone(), your output should look like this:

Now, onto a more complex example. Expand the "Entities" group and click the POST endpoint /domain/{domain}/entities/similar. This one has one URL parameter (domain ID) and a requestObject to supply all other query arguments. On the right side, the interface will show you an example value for the entire object structure, which you can copy to the input field just by clicking on it.

If you use the entire sample value and then click the "Try it out" button, you'll get a response listing three entities that are similar to the seed string "tree".  When you omit the "filter" property (an object itself), from requestObject, you'll see more results. Try changing a few more requestObject properties, such as "string" and "pageSize" to validate the impact on the JSON result returned by the REST API.

In this short article, we've explored the iKnow REST APIs through a convenient GUI that was generated automatically based on the OpenAPI Specification that comes with the iKnow REST APIs. Hopefully it's shown you how to quickly start taking advantage of these APIs and embed them in your applications. To know more about the sorts of operations and their parameters, check the previous article or just open them in Swagger-UI, of course!