7.2.1.1. General Hints

The Axivion Dashboard supports a configurable URL path prefix. This means, if your Dashboard base URL is http://localhost:9090/axivion/ then /axivion/ is the configured path prefix. API entry points are specified relative to the dashboard base URL which includes the URL path prefix. This means, that the API entry point documented as /some_api_entry_point is in fact reachable as http://localhost:9090/axivion/some_api_entry_point for the example dashboard base URL. If you do not want this path prefix to get in your way you can also change it in the Dashboard’s main configuration file dashboard2.config.

In order for the dashboard to know that you are accessing it as a custom API user you have to send along your client type identification. This is done with the HTTP-Header X-Axivion-User-Agent and the value ApiClient.

7.2.1.2. Output format

The API output format is JSON in general. Some entry points allow for the alternative output format CSV. Generally, these are entry points where tabular data is being retrieved, i.e. currently only when retrieving issue lists.

Though in most cases it will not be necessary, it is good practice to tell the server the expected output format using the HTTP Accept header.

When experimenting with the API in your browser you might prefer specifying the required format as a query parameter:

  • format=json, e.g.: http://localhost:9090/axivion/?format=json

  • format=csv (issue lists only)

7.2.1.3. Authentication

Authentication against the Dasbhoard is done using HTTP Basic Auth.

The user name is the same name used to log in to the Dashboard. As password give either your regular password or an ApiToken (recommended). Tokens can be created using this API or via the Dashboard UI on your user profile page.

There is also a custom Authorization-Header you can use to authenticate via token. Its format is:

Authorization: AxToken token

In any case be sure to send along your client type identification as described in General Hints.

7.2.1.4. Error Handling

Virtually every entry point will use the following HTTP error codes:

400:

in case of wrong parameters or some api usage error

401:

in case of missing authentication info / credentials

403:

in case of insufficient permissions to complete the request

404:

in case the project is not found

The generic error format you can parse in order to get further details on an error is:

Error

Describes an error returned from the server
Error

Describes an error returned from the server.

Usually they are caused by wrong API usage but they may also happen in case of bugs in the server

Properties:

  • dashboardVersionNumber (string) Since 6.6.0. a parseable version number indicating the server version

  • type (string) the name of the error kind

  • message (string) A human readable short english message describing the error. Ideally it does not contain any linebreaks.

  • localizedMessage (string) use this instead of message in order to display a message translated according to your language preferences. Will contain exactly the same contents as message in case no translation is available.

  • details (string) Since 7.5.0. Optional error details. Consumers should expect this to be a multiline string and display it in a mono-space font without adding additional linebreaks.

  • localizedDetails (string) Since 7.5.0. Optional translation of details according to your language preferences. Will not be available in case no translation is available.

  • supportAddress (string) Since 7.5.0. Email address for support requests

  • displayServerBugHint (boolean) Since 7.5.0. If this is true, this is an indication by the server, that this error is probably a bug on server-side and clients are encouraged to encourage users to escalate this problem, e.g. using supportAddress.

    Keep in mind that this boolean may be wrong in both directions, e.g.: * if a timeout is configured too low, then this can be a false positive * if the bug lies in the exception judgment than this is a false negative

    So it should always be clear to users that they have the ultimate choice on what to do with an error popup.

  • data (object) Since 6.5.0. Optional field containing additional error information meant for automatic processing.

    • This data is meant for helping software that uses the API to better understand and communicate certain types of error to the user.

    • Always inspect the type so you know what keys you can expect.

    Error types having additional information:

    • type = InvalidFilterException (since 6.5.0):

      • optionally has a string datum ‘column’ referencing the column that has the invalid filter value. The file filter is referred to by the string “any path”.

      • optionally has a string datum ‘help’ providing an ascii-encoded URL pointing to human-readable help that might help a user understanding and resolving the error. If the URL is relative, then it is meant relative to the Dashboard the error originated from.

    • type = PasswordVerificationException (since 7.1.0):

      • optionally has a boolean flag ‘passwordMayBeUsedAsApiToken’ to indicate that the provided password may be used as API token with the respective API. E.g. use ‘Authorization: AxToken …’ header instead of HTTP basic auth.

7.2.1.5. CSRF Protection

The dashboard makes use of the usual technique to provide against the so called Cross-site request forgery or in short: CSRF. It consists in requiring (besides the usual authentication credentials like HTTP Basic Auth or an authenticated browser session) that every request sends along an additional bit of information (a so-called CSRF-Token) that is not available to an attacker tricking a dashboard user into sending a state-changing request to the dashboard from a malicious website.

Sounds complicated, but the good thing is, that this is only required for state-changing requests, i.e. mainly those using the HTTP-Verbs POST, PUT or DELETE but not the more common ones using the HTTP-Verb GET.

As an API-User that wants to do for example a PUT-request you need to first do a GET-request to the Dashboard Info Entry Point in order to acquire such a CSRF-Token. This token will be valid until the server is restarted or until after one week, so usually you only need to acquire the token once at the beginning of your API interaction script.

In the python example you can see how to acquire and send such a CSRF token in practice.