Changes in v2.0¶
v2.0 is currently available as a release candidate for evaluation purposes and is not yet final!
New Obelisk HTTP API (v2)
Obelisk is a continuously evolving platform and after the complete internal overhaul of v1.1, our public HTTP API was in dire need of a facelift. We took into account feedback we've gathered from various partners during the last year and tried to integrate this with our own design goals and lessons learned. Some key changes are:
- The number of operations has been reduced by consolidating a number of features. As a result the API should now be easier to navigate.
- Similar parameters are now consistent in naming and behavior when switching between operations. This way we strive to minimize the learning curve.
- We improved the balance between scalability and usability. The API design steers users away from crippling queries. Clients using the v2 API will have a lower rate limiting footprint when querying in comparison with the v1 API (resulting in more allowed operations per hour).
- Meta-data is back! Scope administrators are now able to describe Things and Metrics using additional properties (e.g. Manufacturer, address of the installation, etc...).
The new API can be explored using the Swagger UI.
The v1 API is now officially deprecated. It is still online to support existing applications, but new clients are recommended to use the v2 API.
New GraphQL Interface
A GraphQL interface was added on top of the new v2 API to enhance the querying capabilities of the platform. GraphQL gives the user more control of the actual response data that is being sent over the wire and allows related data to be retrieved in a single, carefully constructed request.
The GraphQL interface is self-documenting and can be tried out using GraphiQL.
Support for JSON events
Data input for Obelisk was limited to primitive types (Number, String, Boolean) and fixed number arrays of maximum 128 elements. This was a huge restriction for a number of use cases that should otherwise have been a good match. With the goal of making Obelisk more widely adoptable, we introduced support for complex input types in the form of JSON events. For the formal description of JSON Metric types, we decided to rely on the JSON schema specification. A JSON schema can be attached to the Metric metadata, which can then be used for validation.
Some restrictions still apply:
- Only JSON Objects are supported. For other types, the Obelisk native input types should be used.
- JSON Objects are only accepted if they are below the size threshold (32KB for now, same as for native String input).
- Stats queries are allowed for JSON Metric types, but the API will only return results for the numerical top-level attributes of the stored objects (as long as the number of these attributes don't exceed 128).
Fiware NGSI compatibility
Fiware NGSI is becoming an important standard in the application domains that we are targeting with Obelisk. In order to maximize future interoperability, we decided to implement the ngsi-tsdb specification allowing Obelisk to be used in an NGSI ecosystem. The ngsi-tsdb specification defines a historical storage solution which can be connected to NGSI v2 Context Broker implementations to track the historical evolution of Context changes.
The ngsi-tsdb interface can be tried out using the Swagger UI (select Obelisk NGSI-TSDB Interface from the drop-down list!).