Cocon Fiber API Introduction
Cocon Fiber exposes several APIs suitable for retrieving end manipulating asset data.
In order to support different scenarios as good as possible, the entire Cocon Fiber API suite is composed of different categories of APIs, each with their specific characteristics and potential usage scenarios.
Transactional API Exposes the live asset database of Cocon Fiber. It supports retrieval and manipulation of data and assures that all data that enters the system is subject to all necessary business rules in order to assure data integrity and quality.
More information here
Sync API Used for scenarios where an external system needs to be kept in-sync with (a selection of) Cocon Fiber asset data. This API can supply data that has been changed compared to an earlier point in time.
More information here
Read-only API Suitable for high-demand retrieval operations of individual entities or specific sets of data providing more extensive insight in the Cocon Fiber data, combining the information about multiple assets.
More information here
Notification API An event based API to which a system can subscribe in order to receive changes in Cocon Fiber, right after they have taken place.
API Security
The Cocon Fiber APIs are secured in order to prevent information being exposed to unauthorised entities. The following layers of security are present:
Transport security: All APIs are exposed through HTTPS/SSL endpoints using TLS1.2 which guarantees traffic is encrypted between the two communication parties.
API security: Every system and every user needs to present it/him/herself to an API using signed JWT tokens, which are provided by a trusted party. Authorization for a specific API needs to be approved by Speer IT for each identity or group of identities (i.e. organisation).
Functional authorization: Some API's enforce a more fine-grained level of authorization which may cause different behaviour for different users because some user roles may have more extended rights than others. This layer may also present itself by returning more or other information depending on which user interacts with the API.
Failure to meet the proper requirements of each layer, will result in an appropriate error message, which will be an HTTP 401 (Unauthorised) or HTTP 403 (Forbidden) most of the time.
System context versus user context
'Entities' can access Cocon Fiber APIs under one of two different contexts; System context and User context.
System context: Where a (client's) system interacts with a Cocon Fiber API in order to get something done or retrieve information.
User context: Where a specific end-user performs an action through an API. Most of the time implicitly through a front-end, app, etc.
Dependent on the specific scenario, one of both contexts can be applicable. The identities in use for system context interaction are managed by Speer IT, as are the identities that are used for user context interaction. Although in the latter case, a trust can exist between the identity provider of Speer IT and the identity provider of a third party.
System context authentication
In order for a consuming system to authenticate itself to any Cocon Fiber API, it has to provide authentication information via the following HTTP request header parameters:
X-API-Key
X-Client-Id
Values for both parameters are provided by Speer IT.
User context authentication
N.A.
Quality of service (rate limiting and quota)
In order to be able to guarantee quality of service, Cocon Fiber APIs are guarded by rate limiting and quota configuration. This configuration varies depending on the subscription used. Higher subscription tiers will most often indicate higher usage limits.
Whenever a rate limit boundary is exceeded, the API will return with an HTTP 429 - Too Many Requests response.
Whenever a quota is exceeded, the API will return with an HTTP 403 - Forbidden response.
Both responses will be accompanied by a Retry-After response header attribute which will specify when another request will be accepted again.
The consumer of the API is responsible for implementing a proper retry mechanism based on the information above.
Filtering and paging
Cocon Fiber APIs use filtering and paging as a means to control what and in what quantity is returned. The general principles for this are the same, but availability and implementation may vary for specific APIs. When this is the case, it will be explicitly mentioned.
Filtering
Filtering is possible for most RESTful endpoints in the Transactional and Read-only API categories, unless otherwise specified. The exact possibilities for filtering are not generic and are explicitly specified for each API. It can be used to limit the scope of the response returned, depending on the need.
Paging
Paging is used to limit the number of items returned by the API. It can be controlled by the API consumer but is limited to certain maximum values enforced by the API itself. When paging parameters are not explicitly specified, the API will use default values for the page size. Those default values will often be smaller than the maximum values that can be specified manually.
Paged results will always be sorted. Which data of the response is used for sorting is determined by the API itself.
Paging is based on the Offset & Limit principle. The Offset is 0-based, the Limit specifies the number of items in the response. The last page will be indicated by a response of zero items, or a response with a number of items equal to or lower than the page size. It is the responsibility of the API consumer to keep track of the pages consumed and to specify the correct Offset and Limit for retrieving the next page. The Offset and Limit values can be specified using equally named query string parameters.
First Page
/api/v1/buildings?offset=0&limit=200
Next page
/api/v1/buildings?offset=200&limit=200
The limit parameter is subject to a system-defined maximum. The number of results may therefore be smaller than the specified limit.
Versioning
The Cocon Fiber APIs conform to the semantic versioning principles: https://semver.org/
Breaking changes will be indicated by an increment of the major version, while non-breaking changes are indicated by an upgrade of the minor version.
Example:
v1 → v1.1 - Non-breaking change
v1.1 → v2.0 - Breaking change