Cocon Fiber Read-only API

The Cocon Fiber Read-only API is designed with two main scenarios in mind:

1. High-demand data retrieval operations
2. Providing a 'richer' form of insight into Cocon Fiber asset data. It provides pre-defined structures of data, tailored to answer common questions customers have about their asset data and their network in general (e.g. all client connections connected to a POP).

The second scenario avoids the case where a client has to perform multiple requests and combine their responses in order to create a single view.

The read-only API also provides single entity (asset) endpoints which can be used to dynamically query the Cocon Fiber data.

Endpoint types

The Read-only API provides two types of endpoints:

1. Entity based: This type of endpoint conforms to the Speer IT RESTful web service design principles. These endpoints provide the entity based and composite data operations.
2. WMS/WFS: This type of endpoint conforms to the Web Media Service and Web Feature Service interface standards as maintained by the Open Geospatial Consortium (http://www.opengeospatial.org/). The Read-only API does comply to but does not fully implement the interface standard. The page describing the WMS/WFS endpoints (WMS/WFS API) also describes which specific functionality is available.

warning

Note that while WFS can be used by generally available GIS applications like QGIS for visualizing Cocon Fiber assets geographically, there are some limitations to this. Due to the relatively verbose character of WFS features, a potentially very large amount of data needs to be transported. This, combined with the fact that WFS does not support a zoom level concept, makes the WFS API not suited for visualising large areas of fiber networks in tools like QGIS. Appropriate filtering and/or area limiting (i.e. bounded box) is needed in order to assure appropriate performance levels.

Characteristics

Read-only

The Read-only API does not support ways to manipulate data. It does not support POST, PUT, DELETE, etc. operations. The WMS/WFS APIs, which are also part of the Read-only API, also do not support write operations. Even though the WMS/WFS standard itself does have support for such 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 Read-only 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. This is true for both the WMS/WFS endpoints as for the entity based endpoints.

Quality of service

The availability of the Read-only API is similar to the other Cocon Fiber APIs, but especially the entity based and composite data operations can 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 and paging capabilities vary between the entity based endpoints and the WMS/WFS endpoints.

Entity based endpoints

Paging conforms to the general paging principles of the Cocon Fiber APIs. See the general information about paging on the APIs overview page. When filters are available for an API, they can be specified using the filter query string parameter including a filter string.

Example

/api/v1/buildings?filter={FILTER_STRING}

Specific filtering capabilities for the entity based read-only APIs are presented in the following table.

Entity	Filter capabilities	Notes
Building	Attributes: type	Examples: "[type] in ('Pop', 'Ander_Pop_Type') " "not [type] in ('Klant Lokatie', 'Complex', 'Ander_Niet_Pop_Type')"

WMS/WFS endpoints

The WMS and WFS endpoint conform to the WMS/WFS standard for filtering and paging as implemented by GeoServer (https://geoserver.org/).

Paging

Using the startIndex and maxFeatures query string parameters.

Filtering

Using the cql_filter query string parameter and the ECQL query language (https://docs.geoserver.org/latest/en/user/filter/ecql_reference.html#filter-ecql-reference).