Using the ArangoDB Swagger.io Interactive API Documentation

ArangoDB bundles its regular API Documentation also in Swagger.IO API description format. You can browse and explore it interactively via the ArangoDB Webinterface.

Working with the Swagger.io API Tool

Now you’ve loaded the Swagger.io API documentation, let’s play with it. We’re choosing a route that accepts a simple JSON post document. Executing a simple AQL Query does so.

As shown above, we scrolled down to AQL and clicked on POST /_api/query.

It already shows a similar documentation as we could also see on the official HTTP API documentation page.

Now we scroll down past the ready made examples, to the interactive swagger example generation:

You can switch the example JSON window to a model window containing the documentation of the respective JSON attributes. This can aid you during composing a sensible JSON acceptable by the server.

When we click on Try it out the JSON post document becomes editable.

We choose a very simple query, which should introduce no hassle at all (1): RETURN 1, and press (2) Execute:

Swagger will generate an example curl commandline (3) and talk to the ArangoDB Server, and put the result into the output (4). For this example it will re-use the JSON Web Token of your current web-session. Since we may not neccessarily want to use JWT in curl, we will choose HTTP Basic authentification in our shell (for the user root with an empty password):

Since the server would return a not that human readable JSON Document, we use the handy JQ tool to beautify and colorize the json document, so we can better comprehend it.

Working with Swagger.io APIs generated by FOXX

Foxx autogenerates a Swagger API definition for you. To browse that autogenerated documentation, we will install one of the sample apps provided (Itzpapalotl):

We click on the service to get to its overview page:

Clicking on API will open the swagger interface to our itzpapalotl instance:

We choose the random route, and may execute it similar to we previously did with the query interface:

We can see again that the JWT is passed along. Since the routes of a foxx app don’t neccessarily need the authentification of the host, we may also invoke the random route without the token: