Communication
The ACRON REST API by design only supports TLS encrypted communication via the HTTPS protocol. Unsecure, plain HTTP communication is unsupported.
SSL Certificate
The use of a SSL certificate for server authentication is mandatory. It is strongly recommended to acquire a certificate through a trusted certificate authority.
For testing purposes, a self-signed certificate is also applicable. Such a certificate may be created using the REST API configuration in the ACRON Admin. A self-signed certificate will by default be marked as not trustworthy by a client and would have to be added to the windows trusted root certificate store to remove this warning permanently.
Request Format
The default Content-Type header is "application/json".
The only supported Accept format is also "application/json".
The Accept-Encoding header is optional, by default Brotli ("br") is assumed. Other supported options are gzip ("gzip") and "none".
The Authorization header is used to pass a Bearer token for application level authentication, while the "Acron" header is used in a similar fashion to pass a token for user level authentication.
For operations that require access rights and user credentials the "Authorization" and "Acron" headers are mandatory.
Response Format
The ACRON REST API uses the "response consistency" pattern, assuring all responses follow a pre-defined structure.
These responses include the following:
•AcOkResponse
•AcBadModelStateResponse
•AcBadRequestResponse
•AcExceptionResponse
•AcServicesUnavailableResponse
•AcUnauthorizedResponse
•AcUnsupportedApiVersionResponse
For a detailed overview, please refer to the ACRON REST API Swagger documentation.
Versioning
The ACRON REST API version corresponds to the version of the installed ACRON software. A version argument may be passed as part of a route, e.g. https://[HOSTNAME]:[PORT]/api/v9.5/Test/HelloRestApi.
In the case of breaking changes between versions, an operation may be invoked for the previous version explicitly, e.g. https://[HOSTNAME]:[PORT]/api/v9.4/Test/HelloRestApi to yield the expected behavior.
If no version argument is passed as part of a route, the current version of the ACRON REST API is assumed for the operation.
It is strongly recommended to always invoke routes explicitly with the ACRON REST API version the client application was built against,
so as not to break functionality of the client application when updating the ACRON software to a newer version.
Authentication
The ACRON REST API uses two layers of authentication:
Application-level Authentication
Each client application is assigned a so called "access right" in the ACRON Admin, a set of credentials it uses to authenticate itself to the ACRON REST API.
Disabling or deleting a set of access rights in the ACRON Admin prevents the application that uses said credentials from accessing the ACRON REST API.
User-level Authentication
Most API methods require a valid user login. Users and user permissions are configured using the ACRON Designer.