API explorer console¶

api console

The AyaNova server uses Swagger-ui to provide an interactive live API explorer and documentation console for developers to learn about and experiment with the AyaNova REST API.

WARNING¶

BEWARE This console operates on the live data on your server! If you are experimenting, particularly with routes that modify data, we highly recommend installing a separate trial version of AyaNova just for experimentation purposes.

How to access the API explorer console¶

There are two ways to access your AyaNova server's API explorer console:

From the server api 'meta' page¶

server home

You can select the option to open the console from the servers api meta page pictured above, append /api/v8/ to your server url to access this page.

Directly by address¶

You can access the api explorer console by navigating with your browser to this path on your AyaNova API server: /api-docs/

For example if your AyaNova server were located on port 7575 of the local computer you would connect to it via this url: http://localhost:7575/api-docs/

Using this console you can see real working examples of exactly what is required for headers and body contents of requests and the responses returned to use with your own development environment.

Authentication¶

Most of the API endpoints in AyaNova require a JSON web token authentication to use them. The API console supports the ability to set a authorization token so you can fully test all routes.

To obtain a token expand the "Auth" route in the main console and enter a value for login and password and click on the "Try it out" button to obtain an API token.

The "response body" section will contain the return value, something similar to this:

{
    "ok": 1,
    "issued": 1518034370,
    "expires": 1520626370,
    "token": "xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpqE4MDM0............fQ.z7QaHKt2VbcysunIvsfa-51X7owB1EYcyhpkdkfaqzy",
    "id": 1
}

The highlighted line above contains the token (shortened for illustration) you require, copy the token value not including the quotation marks. This is your access token.

Click on the "Authorize" button at the top of the API console and a popup dialog box will open. In the "Value" box the dialog enter your api token, for example using the above you would paste in:

xyGhbGciOiJIUzI1NiIsInR4cCI6IkpXVCJ9.utJpqE4MDM0............fQ.z7QaHKt2VbcysunIvsfa-51X7owB1EYcyhpkdkfaqzy

then click on the "Authorize" button inside the popup dialog box.

You have now saved your credentials (until you close or reload this browser window) and can access any of the API endpoints in this test console you have permission to access with the credentials you supplied earlier.

Use web app JWT¶

It can sometimes be useful as a developer to be able to simultaneously use the AyaNova UI and the developers console with the same account logged in.

To do this login with the web app as normal but with the web browser developer console open and in the browser's developer console "Network" tab copy the JWT token being sent in the Request Header and paste that into the AyaNova API explorer Authorization dialog.

This avoids the issue with a login invalidating prior JWT issued to the same User account.

web app JWT