Cocon Fiber Transactional API
The Cocon Fiber Transactional API is an API, or rather a collection of API's, targeted to manipulating asset data. An important aspect of this category of Cocon Fiber API's is that all necessary validations are performed in all circumstances in order to guarantee the highest level of data integrity in a consistent way.
There are roughly two types of transactional API's:
- Generic operations for manipulation of individual assets, or manipulation of assets within the context of others (e.g. buildings or access points).
- Specific operations manipulating a number of assets together in order to achieve a certain goal (e.g. performing a delayed connection, or signalling the presence of a person in a location).
The information for the first category is described on this page. For specific operations, individual pages are available.
Characteristics
Actuality of data
The transactional API's manipulate assets in the Cocon Fiber database. Changes are effective immediately.
However, it may take some time before the Sync API and the Read-only API reflect the changes.
Quality of service
The availability of the transactional API's is similar to the other Cocon Fiber API's.
Dependent on the type of subscription, specific rate limiting and/or quota measures may be in effect though (see the general rate limiting information on the API's overview page).
Filtering and paging
Filtering can be applicable to certain GET requests. Whenever this is the case, it will be explicitly described for the relevant operations.
Paging conforms to the general paging principles of the Cocon Fiber API's. See the general information about paging on the API's overview page.
Security
The transactional API's use system as wel as user context authentication. See the general information about authentication mechanics on the API's overview page.
When the API is used in the context of a user, specific authorization checks may be in effect, preventing manipulation of (certain parts of) data. This depends on the user rights that apply to the user in which context the API is called. Because user specific authorization is in effect. The results of GET requests may also differ between users at the same moment in time, as a user only receives the information he/she is entitled to receive based on their authorization.
Usage Guidelines
This information will be extended when general transactional API (i.e. general manipulation of Cocon Fiber assets) functionality becomes available.
Error Responses
The transactional Cocon Fiber API's have a generic way of returning error information.
In case an error occurs, the response will include an error object with the following structure:
{
"timestamp": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": 0,
"errors": [
{
"code": "string",
"message": "string"
}
],
"message": "string"
}
The specific error code(s) and message(s) will vary depending on the encountered issues.
What errors are returned in which circumstances will be determined by the specific functionality. But in general, an attempt will be made to gather as much errors as possible as part of a single operation. This prevents having to do multiple calls in order to get things right.