This document describes the format of the Appclusive REST API

Introduction

Appclusive exposes its functionality via an ODATA v3 compatible REST API. So instead of repeating the way how ODATA works in this document we will describe how Appclusive models it entities and advertises its services.

Authentication

Appclusive supports different authentication mechanisms independent of the underlying transport protocol which can be extended by plugins. Currently the following authentication means are available:

  • Windows Integrated, ActiveDirectory (via Authorization header)
  • Basic (via Authorization header Basic with Base64 encoded username and password)
  • OAUTH2 (via Authorization header with Bearer token)

Appclusive does not act as an Identity Provider but relies on external systems to provide that functionality.

For more information about Authentication see the chapter about Security.

Uri Format

Appclusive distributes its functionality across several separate endpoints:

  • Diagnostics

    httpS://appclusive.example.com/api/Diagnostics

  • Core

    httpS://appclusive.example.com/api/Core

  • Model

    httpS://appclusive.example.com/api/Model

These endpoints can be extended by means of plugins. Depending on the endpoint several entity sets are accessible. To determine the exact functionality each endpoints exposes its schema via httpS://appclusive.example.com/api/endpoint/$metadata.

For a specific entity set consult the respective documentation.

DFTODO list entity sets per endpoint

API Operations

In general each entity set supports basic CRUD operations:

Read

List

Retrieving entities is performed by an HTTP GET operation. ODATA filter operators and paging semantics apply.

Example: GET httpS://appclusive.example.com/api/Core/KeyNameValues

HTTP 200 is the usual response when entities are returned. The response body will then contain a list of entities that match the request criteria.

Note: if no entities are found that match the request criteria an empty list is returned. The response will still be HTTP 200.

Single

To retrieve a single entity the entity id is placed in brackets after the entity set:

Example: GET httpS://appclusive.example.com/api/Core/KeyNameValues(42L)

HTTP 200 is the response and the response body will contain the entity specified by its id. If no entity exists the response will be HTTP 404.

Note: all ids are of type long (or int64), so they should be suffixed by a capital L.

Note: if a client requests an entity from a different tenant where the client does not have permissions to retrieve that entity, the HTTP response will also be HTTP 404 (to prevent information disclosure).

Create

Creating an entity is normally performed by an HTTP POST operation.

Example: POST httpS://appclusive.example.com/api/Core/KeyNameValues

The body of the HTTP requests depends on the actual entity set (which can be determined by the aforementioned $metadata schema.

HTTP 201 indicates that the entity has been created. The response body will then contain the new entity.

HTTP 202 indicates that the operation has been accepted, but has not been completed yet. The Location header of the HTTP response will contain an Uri to a Job entity which can be tracked by the client.

Note: when requesting the instantiation of Blueprints the actual creation is not performed directly via HTTP POST, but performed via an Order.

Update

Updating existing entities can be performed in two different ways:

Full Update

An HTTP PUT operation expects the complete entity in its HTTP body (regardless of whether an attribute has changed or not).

Example: PUT httpS://appclusive.example.com/api/Core/KeyNameValues(42L)

Partial Update

With HTTP PATCH the HTTP body may only contain the actual attributes that have changed and should be updated, eg. the Name of a KeyNameValue.

Example: PATCH httpS://appclusive.example.com/api/Core/KeyNameValues(42L)

{
  "Name" : "Updated Name"
}

HTTP 204 indicates a successful update operation where no content is returned in the response body. To get the updated entity (especially useful with PATCH operations, a new GET request must be performed.

Note1: do NOT use HTTP MERGE, but always use HTTP PATCH. Note2: Appclusive uses upper camel case.

Delete

To delete an entity an HTTP DELETE must be performed:

Example: DELETE httpS://appclusive.example.com/api/Core/KeyNameValues(42L)

HTTP 204 indicates a successful delete operation where no content is returned in the response body.