Principe d'organisation des API et du SDK

Définition d'une API

Article pédagogique "Qu'est-ce qu'une API ?" : https://www.redhat.com/fr/topics/api/what-are-application-programming-interfaces

Organisation de nos API par couche

Nos API se déclinent en plusieurs couches :

• Les couches basses, composées du SDK et de l'API graph, sont très riches et formelles. Elles permettent d'accéder au parcours du jumeau numérique décrit sous la forme d'un graph dans le BOS Spinalcore. Elles donnent accès aux ontologies, à la sémantique, aux objets et attributs du jumeau numérique.

• Les couches supérieures donnent des accès plus directs à certains univers de données : l'organisation et les objets géographiques, les workflow, les réseaux IoT ou BMS, les équipements et groupes d'équipement... Notons que toutes ces données spécifiques "héritent" des nœuds du graph Spinalcom. Ces données sont donc aussi accessibles de manière plus formelle via l'API graph de la couche basse et dans le SDK.

Exemple : API d'échange du référentiel géographique

Le référentiel géographique correspond au socle de description du bâtiment qui doit être partagé par l'ensemble des applications agissant sur le bâtiment (Bâtiment/étage/local/équipement...). Ce référentiel géographique, ou "contexte géographique", est une ontologie particulière importante dans le bâtiment.

Il existe plusieurs manières pour récupérer cette ontologie :

1. Utiliser l'API Spécifique :

• api/v1/context/geographicContext

2. faire un parcours du graph

• api/v1/context/list - récupérer la liste des ontologies prédéfinies, trouver dans cette liste le contexte de type "geographicContext", récupérer son id unique

• api/v1/context/{id}/tree - demander l'arborescence de ce contexte à partir de son id

3. Faire un parcours du graph noeud par noeuds :

• api/v1/context/list - récupérer la liste des ontologies prédéfinies, trouver dans cette liste le contexte de type "geographicContext", récupérer son id unique

• /api/v1/relation/{id}/children_node - en partant du nœud bâtiment, tous les nœuds fils qui sont des étages

• /api/v1/relation/{id}/children_node - en partant de chaque nœud étage, tous les nœuds fils qui sont des pièces

• /api/v1/relation/{id}/children_node - en partant des nœuds pièces, tous les nœuds fils qui sont des objets BIM avec des classes BIM spécifiques (nous voulons par exemple la liste des équipements CVC ou luminaires pour une pièce et pas forcément les objets de corps d'état architecturaux)

Documentation et teste de nos API avec Swagger

Toutes nos API sont documenté en utilisant la spécification OpenAPI (anciennement spécification Swagger). Vous pouvez donc accéder à leur documentation et les tester directement en ligne.