home shape

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.

Serverapi-overview

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:

Serverapi-swagger-formular

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.

Switch-To-Model

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:

Serverapi-swagger-edit

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):

Serverapi-xterm

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):
Foxx-install-itzpapalotl

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

Foxx-itzpapalotl-overview

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

Foxx-itzpapalotl-swagger-overview

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

Foxx-itzpapalotl-swagger-execute

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:

Foxx-curl-xterm

Willi Goesgens avatar 1452092470 92x92

Willi Goesgens

Willi is part of ArangoDB Core team. He primarily works on performance tuning, the release process of ArangoDB and helping the community with his broad experience.

Leave a Comment





Get the latest tutorials, blog posts and news: