Integration Server REST API

The Integration Server REST API provides access to the Altitude Software Object Model as exposed by the Integration Server. The API can be used on development environments based on the REST framework.

The Integration Server is a middleware server that integrates third-party applications with the Altitude uCI Server. The Integration Server unifies API access to the Altitude uCI Server and enables the development of components that access third-party applications via the Altitude uCI Server.

Features

Features of the Integration Server REST API include:

• Supports several Integration Server API versions, meaning client applications do not have to be recompiled when the Integration Server API evolves.
• Resources on the server side are accessed by URLs over HTTP and HTTPS.
• Supports application/json messages payload media type.
• The API requests are protected by OAuth 2.0 security tokens.

Event triggering

The Integration Server REST API supports the following event triggering mechanisms:

• Long polling: Applications continuously invoke the method WaitForEvent to get the events. There is also a server-side queue for each application to avoid losing events. The server delays each request response until an event is triggered or the polling timeout is reached. On reaching the timeout, the client will send a new request and wait again until the events are triggered. This requires the client to handle this on a separate thread to avoid freezing the main thread of the main interface.
• Webhook: The Integration Server sends events to endpoints previously registered by applications. The applications must have a server component. If events must be sent to a browser, please consider using, for example, SignalR or WebSockets. The client implements a REST web server conforming to the webhook API specification on the integrationServerWebHook.json swagger file, and the Integration Server calls this API whenever an event is triggered. This mechanism typically requires that, since the client is a web application, the application should have a server-side component listening for the events and being able to push the events to the client side.

  Note To keep the connection with the Integration Server, if you are receiving events using webhooks, when you receive a PingEvent, you must invoke the method instance.PingReply.

API specification

The API is specified in an OpenAPI 2.0 specification file (Swagger file), named IntegrationServerRestApi.json.

Developers can generate client code in any programming language from the Swagger file using open source tools, like MS Autorest, or SwaggerHub.

Version compatibility

The following table displays the compatibility of the Integration Server REST API with the Altitude uCI Server: