Contact usRequest a demo

This document describes version 5 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 5 ended on 22 November 2021. 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.

To go directly to the Web API documentation: Unblu Web API

OpenAPI / Swagger Specification

Wikipedia :

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

<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 Lifecycle

The version lifecycle 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 lifecycle to ensure compatibility with existing consumers of the old API.

For example, Unblu 4.3 was shipped with version v1 of the API and Unblu 5 introduces changes that are not backwards compatible with v1:.

  • A new version v2 is introduced and v1 is provided as a compatibility layer.

  • Both versions are available and can be used in parallel.

  • When the next version v3 is introduced (which could be, for example, in Unblu 6, or later), it is possible that the v1 version 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.

Migration from v1 to v2

  • The userauthenticator service is renamed to authenticator service.

  • In v1 The boolean parameter isParentTeamItselfAllowed in the /teams/teamIsChildOfOtherTeam service had no effect (it was considered as always true) with v1. This parameter has been removed in v2.