|
This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version. The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu. |
Web API
The Web API is aligned to REST services.
The Unblu Web API provides a set of URLs that you can send HTTP requests with a JSON payload to for the purpose of triggering certain behavior in Unblu.
To go directly to the Web API documentation: Unblu Web API
OpenAPI/Swagger specification
The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful Web services.
Starting with Unblu 5 an OpenAPI specification describing all REST services can be used to generate client applications that call the Unblu server. Integration with other tools supporting this standard is also easier.
Request URL structure
The technical details for each service endpoint can found here or in the OpenAPI specification, but all URLs always look the same:
<prefix>/rest/<version>/<service name><parameters>
Where:
<prefix>: base path of the installation
-
Unblu Financial Cloud:
https://start.unblu.com/unblu -
On-premises: depends on the installation and the call origin definitions used:
<version>: version of the API, see API Versioning.
<service name>: name of the service. The services are grouped by topic. Examples for users: /users/findByUsername, /users/create …
<parameters>: parameters of the service. Depending on the case, these can be path parameters (such as /webhookcalllogs/getCallLogForWebhookRegistration/{registrationId}) or query parameters (such as /accounts/findByName?name=)
API versioning
Version identifier in the URL
The version identifier (v1, v2 …) is part of the URL of each service (see Request URL Structure). In this way, one Unblu server installation provides multiple API versions.
If you are migrating from Unblu 4.x, see also Implicit Version below.
Version life cycle
The version life cycle of our API is not bound to the Unblu version:
-
A new API version is introduced as soon as a breaking change is introduced into the API.
-
If no breaking change is introduced, the same API version can be used over multiple Unblu (major) versions (5.x, 6.x, etc.).
-
When a new API version is introduced, the old version is kept for the duration of one major version life cycle to ensure compatibility with existing consumers of the old API.
For example, Unblu 5 was shipped with version v2 of the API and Unblu 6 introduces changes that are not backwards compatible with v2:.
-
A new version
v3is introduced andv2andv1are provided as a compatibility layer. -
All versions are available and can be used in parallel.
-
When the next version
v4is introduced (which could be, for example, in Unblu 7, or later), thev1version (and maybev2) will no longer be available.
Differences between version 5 and 4.3
Implicit Version
With 4.3 it was possible to ignore the version declaration in the URL.
GET <prefix>/rest/teams/getAll
Which was the same service as:
GET <prefix>/rest/v1/teams/getAll
This is no longer possible. The version identifier must be part of the URL.
Case sensitivity
Up to, and including, version 4.3 it was possible to use both UPPER and lower case text in calls.
For example, for the following call it was possible to use either userid or userId:
GET <prefix>/rest/v1/userauthenticator/impersonate?username=<string>&userId=<string>&superUser=<boolean>
This is no longer possible, the documented case type must be used.