Chimera API, version 3

This page documents version 3 of the API, which is introduced in release 1.5 and will be used by the new Chimera frontend from release 1.6 onward. API v3 is nearly a complete redesign of the API v2.

Main changes v2 -> v3

• separate APIs for history, config, user management, analytics are merged
• renaming scenario -> case-models, instance -> cases
• inclusion of resources organizations and users (see #75)
• API documentation in OpenAPI 3 format automatically generated by Swagger (see #100)
• adherence with the documented API principles

OpenAPI

To automatically generate the API documentation openAPI uses annotations in the source code. The generated API documentation is deployed with the Chimera instance to the endpoint /swagger, e.g. https://bpt-lab.org/chimera-dev/swagger.

API design principles

This section documents the principles that were used in the design of the Chimera API v3 (as required by #102).

General considerations

1. a version number is included in the URI
2. the base path for the API is api/v{version-number} (no separate APIs api/history/v2, api/interface/v2, api/config/v2, and api/analytics/v2 like in version 2)

Naming conventions

1. resources are named by nouns, only operations use verbs
2. only lowercase used in URLs
3. resources that represent collections, e.g. users, are named in the plural form
4. resources names with several name parts are connected using a hyphen, e.g. case-models (suggested in RFC3986)
5. attributes in responses are written in camelCase

Use of query parameters

Query parameters are used to filter activities according to their state, e.g. init or running.

• pagination (so far not used)