Cocon Fiber Sync API

The Cocon Fiber Sync API is an API which can be used to synchronize asset data between Cocon Fiber and some external system. The typical use case is a scenario where some external system needs an integral view of (parts of) the Cocon Fiber asset data in order to do its own analysis. Rather than requesting specific data on-demand. For this purpose, the Sync API is able to provide the modifications (inserts, updates and deletes) for assets since a specific moment in time. The Sync API consumer can then update its own representation of the current situation in its own system(s).

The general Sync API mechanics are as follows:

1. The API consumer requests the updates for a specific asset, specifying the since timestamp and paging information.
2. The API returns the relevant changes to that asset, based on the provided information.
3. The API consumer requests additional pages when needed.
4. The above steps are repeated for each relevant asset.

Assets are returned by the Sync API in a 'latest state' fashion. All of the attributes of an asset are returned, also in cases where just one of them has changed. Inserts and updates are provided as upsert (e.g. combined insert and update). It is the responsibility of the consuming system to determine if, in its context, they are to be considered a new or an updated item. For deletes, only the ID of the deleted asset is returned.

Characteristics

Read-only

The Sync API does not support ways to manipulate data. It does not support POST, PUT, DELETE, etc. operations. Actuality of data In order to be able to support a high demand for data without negative impact on the asset management system itself, the Sync API operates on an abstract of the live Cocon Fiber database. This means that the data may be out-of-sync with a maximum timespan of 24 hours.

Quality of service

The availability of the Sync API is similar to the other Cocon Fiber APIs, but the Sync API is designed to handle a much higher demand. 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 APIs overview page).

Filtering and paging

Filtering is not applicable for the Sync API. Paging conforms to the general paging principles of the Cocon Fiber APIs. See the general information about paging on the APIs overview page.

Security

The Sync API uses system context authentication. See the general information about system context authentication on the APIs overview page.

Usage Guidelines

There are certain specifics with regard to the usage of the Sync API, which are described below.

General usage

Modifications are requested on a per-asset basis. The general structure of a Sync API request is as follows: GET /syncapi/v1/{asset}/changes?since={timestamp}&offset={offset}&limit={limit}

This will return a maximum of limit upserts and limit deletes, counted from offset, modified since since.

note

Refer to the list below to see which information about which assets are currently provided by the Sync API

Since parameter

The since parameter is used to specify a point in time from which the consumer want to check if there are any modifications to the requested asset.

• Format: yyyy-MM-ddTHH:mm:ss.SSSZ (ISO8601 in UTC)
• Example 2023-04-05T13:49:26.232Z

GET /api/v1/buildings/changes?Since=2023-04-05T13%3A49%3A26.232Z

Offset/Limit specifics

The GET /buildings/changes endpoint uses pagination in the form of an offset and limit parameter. A request like GET /buildings/changes?Since=2023-04-05T13%3A49%3A26.232Z&offset=0&limit=10 will respond with a list of 10 changed buildings and a list of 10 deleted (IDs of) buildings. The request GET /buildings/changes?Since=2023-04-05T13%3A49%3A26.232Z&offset=10&limit=10 will return the next 10 changes and deletes from the timestamp provided in the 'since' parameter. The offset/limit query parameters are optional and will have the following default value:

• offset=0
• limit=10

When desired to request a list of a maximum of 200 building changes and a maximum of 200 deletes the first request should look like this: GET /api/v1/buildings/changes?Since=2023-04-05T13%3A49%3A26.232Z&offset=0&limit=200 Followed by: GET /api/v1/buildings/changes?Since=2023-04-05T13%3A49%3A26.232Z&offset=200&limit=200

note

The limit parameter is subject to a system-defined maximum. The number of results may therefore be smaller than the specified limit.

note

Note that in the case of the Sync API, the offset and limit parameters do not specify the total number of returned items. Instead, they relate to the number of items returned for upserts and deletes separately. This means that a request with a limit of 200 may return a maximum of 400 items in total. It also means that the first request might return 100 upserts and 200 deletes and the second request zero upserts and 100 deletes.

Dependencies

The information returned contains relevant references to other entities. These reference are static and will not change during the lifetime of those assets. However, the API consumer will need to handle referential integrity in its own systems. For instance, in the situation where a delete is received from the Sync API for a certain asset, the API consumer needs to handle cases where there is still a reference to that asset from assets that haven't been updated in their systems yet. So during the synchronisation session, temporary periods of time may exists where the data in the receiving system is not conform referential integrity rules.

Available asset types

The Sync API exposes the following Cocon Fiber asset types:

• Accesspoint
• AccesspointType
• Building
• BuildingType
• Cable
• Drilling
• DrillingType
• Duct
• Enclosure
• EnclosureType
• Frame
• Permit
• Project