APIs & SDK Organization Principle

Organization of our APIs by layer

Our APIs are divided into a couple layers:

• The bottom layers, composed of the SDK and API graph, are very rich and formal. They make it possible to access the journey of the digital twin described as a graph in the SpinalCore BOS. They give access to ontologies, to semantics, to objects and attributes of the digital twin.

• The upper layers give more direct accesses to certain data universes: the organization and geographic objects, the workflows, the IoT networks or BMS, the equipment or equipment groups... Let's highlight the fact that this specific data "inherit" knots from the SpinalCom graph. This data is therefore also accessible in a more formal manner through the API graph of the bottom layer and in the SDK.

Example: the exchange API of the geographic reference frame

The geographic reference frame corresponds to the foundation of the description of the building which has to be shared with all the applications affecting the building (Building/floor/room/equipment...). This geographic reference frame, or "geographic context", is a particular ontology important in the building.

There exists several manners to recover this ontology:

1. Use the specific API

• api/v1/context/geographicContext

2. Draw a graph journey

• api/v1/context/list - recover the list of predefined ontologies, find in this list the type of context "geographicContext", recover its unique ID

• api/v1/context/{id}/tree - demand for the tree view of this context from its ID

3. Draw a graph journey knot by knot:

• api/v1/context/list - recover the list of predefined ontologies, find in this list the type of context "geographicContext", recover its unique ID

• /api/v1/relation/{id}/children_node - by starting by the building knot, all the child knots that are floor levels

• /api/v1/relation/{id}/children_node - by starting by the floor level knot, all the child knots that are rooms

• /api/v1/relation/{id}/children_node - by starting by the room knot, all the child knots that are BIM objects with specific BIM categories (for instance, we want the list of CVC equipment or lighting for a room but not necessarily architectural interior objects)

Documentation and test of our APIs with Swagger

All our APIs are documented by using the Open API specification (formerly Swagger specification). Thus, you can access their documentation and test them online directly.