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 generally JSON. Some entry points allow for the alternative output format CSV. Generally, these are entry points where tabular data is 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/api?format=json

  • format=csv (issue lists only)

7.2.1.3. Authentication

Authentication against the Dashboard is done using HTTP Basic Auth.

The user name is the same name used to log in to the Dashboard. For the password, provide 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 incorrect parameters or an API usage error

401:

in case of missing authentication information or 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.

    • type = SAMLSessionExpiredException:

      • has a string datum ‘providerName’ naming the SAML identity provider whose session expired, so the client can re-login via that provider.

    • type = UnauthenticatedException | InvalidCredentialsException (since 7.13.0)

      • optionally has a key ‘apiTokenIdentityProviders’ which refers to a map: federatedIdentityProviderName (string) → apiTokenCreationUrl (URI) allowing to assist the creation of ApiTokens for these providers - so that the necessary credential can be created more easily.

7.2.1.5. CSRF Protection

The dashboard uses standard techniques to protect against so-called Cross-site request forgery (CSRF). This consists of requiring (besides the usual authentication credentials like HTTP Basic Auth or an authenticated browser session) that every request sends along an additional piece of information (a 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.

While this sounds complicated, it is only required for state-changing requests – 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 who wants to make a PUT request, for example, you need to first make a GET request to the Dashboard Info Entry Point or to /api/create_csrf_token in order to acquire a CSRF token. This token will be valid until the server is restarted or for 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.