Introduction oData API

L'API Web Syfadis oData a été implémentée pour être conforme au protocole standard oData V4.0.

L'Open Data Protocol (oData) est un protocole permettant le partage de données via les formats Atom ou JSON. Ce protocole permet la création et la consommation en RESTful. En d'autres termes cela permet à un client web, à partir de simples messages HTTP de publier et éditer des ressources identifiées dans l'URL et définies dans le modèle de données de Syfadis.

Pour en savoir plus http://www.odata.org/documentation/

Concernant notre API Web, le Endpoint (ou point d'entrée) est le suivant : odata-api

De ce fait, toutes les URLs utilisant l'API oData Syfadis commenceront de la façon suivante : https://host/odata-api: ("host" étant le nom du serveur.)

Toutes les fonctions de la norme oData ne sont pas implémentées dans notre API.

Ce document ne tient pas compte des éventuelles personnalisations réalisées sur les champs des entités. Ainsi, la description des propriétés faite dans ce document est la description des propriétés en standard.

Nouveautés

Vocabulaire

L'application Syfadis est constituée « d’entités » qui organisent et enregistrent intelligemment les données du LMS.

Une « entité » décrit les informations concernant un objet tel qu’un utilisateur, une formation, une session etc...

Chaque colonne d'une entité est appelée « propriété ».

Une entité peut avoir plusieurs propriétés.

Certaines de ces propriétés peuvent être d’autres entités ou des collections d’entités. On parle alors de « propriété navigable ». Il faut alors utiliser l’option d’élargissement pour y accéder en détail et réaliser des opérations de liaison entre objets pour les manipuler.

Une « entité exposée » est une entité qui est mise à disposition par l'API Web oData.

Le caractère exposé ou non d'une entité est vérifiable par la consultation du $metadata.

« Users » est une entité définie dans Syfadis, exposée via l'API Web Odata, qui contient les informations des utilisateurs du système de gestion de l'apprentissage (LMS) au sein de l'entreprise.

L’entité « Users » a des propriétés telles que FirstName, LastName, Address ...

L’entité « User » a des propriétés de navigation telles que Domains, Structures

Les entités exposées

Implémentation

Format d’échange

Syfadis implémente uniquement le format d’échange de donnée JSON.

Le seul élément n'étant pas exprimé en JSON est le fichier de métadonnée qui est exprimé en XML.

JSON est un format léger d'échange de données qui est à la fois facilement éditable et lisible par l'homme mais également simple à interpréter et à générer par les machines. Il est indépendant de tout langage et utilise les conventions qui sont familières à la majorité des développeurs. Des interpréteurs JSON sont déjà disponibles pour quasiment tous les langages de programmation. Ces propriétés font de JSON un langage idéal pour les échanges de données.

Pour en savoir plus : http://www.json.org

Options

oData supporte de nombreuses sortes d'options de requêtage.

Sont détaillées ci-dessous, les options de requêtage implémentées par Syfadis.

Attention : le nom des entités et le nom des propriétés utilisés dans les URL sont sensibles à la casse. Une erreur dans la casse d’une entité conduit à une erreur 500 avec dans le corps du message The controller for path '/odata-api/xxx' was not found or does not implement IController.

Filtrage ($filter)

L'option $filter, permet de filtrer une collection d’entités.

L'expression spécifiée par le "$filter" est évaluée pour chaque ressource dans la collection. Ne sont retournés, seulement les items satisfaisant la condition spécifiée.

Filtrage sur une propriété de l’objet requêté :

/odata-api/Users?$filter=FirstName eq 'Pierre'

/odata-api/Users?$filter=contains(Name,'Pier')

/odata-api/Domains?$filter=Father0 eq null

/odata-api/Users?$filter=FirstName eq 'Pierre' and DeletedOn eq null

Filtrage sur une sous-propriété de type collection avec les opérateurs ANY et ALL :

/odata-api/TrainingSessions?$filter=Tutors/any(it:it/Domains/any(d:d/Name eq 'France')) (filtre les sessions dont au moins un formateur appartient au domaine France)

/odata-api/TrainingSessions?$filter=Tutors/all(it:it/Domains/any(d:d/Name eq 'France')) (filtre les sessions dont tous les formateurs appartiennent obligatoirement au domaine France)

Filtrage sur des sous-propriétés :

/odata-api/TrainingSessions?$filter=Training/OptionalEnumField2 eq '100'&$expand=Training (filtre sur les sessions dont la formation a un OptionalEnumField2=100)

Toutes les possibilités de filtrage ne sont pas listées dans ce document. Pour une description détaillée des possibilités, voir les liens ci-dessous :

http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752358

Ordre ($orderby)

L'option $orderby, permet de trier une collection d’entités, par ordre croissant ou décroissant.

Si la précision de l’ordre n’est pas spécifiée, alors la collection est triée par ordre croissant. Enfin, si l’option d’ordre de tri n’est pas spécifiée, les données sont triées par ordre croissant sur l’id.

/odata-api/Users?$orderby=LastName

/odata-api/Users?$orderby=LastName desc

Combinaison de l’option « filter » + option « order by »

/odata-api/TrainingSessions?$orderby=StartedOn&$filter=StartedOn gt 2018-01-01T00:00:00Z and StartedOn lt 2018-03-08T23:00:00Z

Limite et saut

L'option $top, permet de ne récupérer que les n 1ères entités de la collection.

L'option $skip, permet d'ignorer les n 1ères entités de la collection et de récupérer toutes les entités suivantes (saut).

/odata-api/Users?$orderby=LastName desc&$top=5&$skip=2

Comptage

L’option $count, permet de compter les entités qui résultent de la requête, et d’en retourner ce nombre au lieu de la collection.

/odata-api/Users/$count

Élargissement (expand)

L’option $expand, permet d’élargir les propriétés de navigation de la réponse pour y inclure les entités dépendantes. (En lien avec l’entité principal).

La requête suivante retourne les utilisateurs tout en incluant les propriétés de navigation Domains et Jobs:

/odata-api/Users?$expand=Domains,Jobs

Sélection

L’option $select, permet de limiter le nombre de propriétés retournées.

Sélection d’une propriété de l’objet requêté :

/odata-api/Users?$select=FirstName,LastName

Sélection de sous-propriétés :

/odata-api/Trainees?$select=LmsProgress&$expand=User($select=Code),TrainingSession($select=FinishedOn;$expand=Training($select=Name)) : sélection de la progression de l’inscription, du code de l’utilisateur inscrit à la session, de la date de fin de la session et du nom de la formation.

Exemple d’utilisation de sélections et filtres combinés :

/odata-api/Trainees?$select=LmsProgress&$expand=User($select=Code),TrainingSession($select=FinishedOn;$expand=Training($select=Name))&$filter=User/Code eq 'XXX' and (LmsProgress eq 'NotAttempted' or LmsProgress eq 'Incomplete') and RegistrationOrigin eq 'BackOffice' and TrainingSession/DeletedOn eq null and DeletedOn eq null

Fonctions sur les propriétés « texte »

Les fonctions ci-dessous peuvent être utilisées dans les requêtes de sélection sur les propriétés de type « texte » :

• tolower : convertit la valeur de la propriété passée en paramètre en minuscule

• toupper : convertit la valeur de la propriété passée en paramètre en majuscule

• trim : supprime les espaces en début et fin présents dans la valeur de la propriété passée en paramètre

Exemples :

/odata-api/Trainings?$filter=toupper(Code) eq 'A001'

/odata-api/Trainings?$filter=toupper(trim(Code)) eq 'A001'

/odata-api/Trainings?$filter=contains(tolower(Code),'a001')&$expand=PrimaryDomain

Opérations non supportées

• La pagination pilotée par le serveur (server-driven paging) n'est pas supportée pour les retours de résultats partiels Nous recommandons l'utilisation des primitives $top et $skip afin de gérer la pagination.

• L'option de recherche $search n'est pas supportée.

• L’opérateur IN n’est pas supporté.

• L'opération UPSERT n’est pas supportée.

• Les requêtes HTTP de mise à jour d'entité de type PUT sont supportées mais elles sont interprétées comme un PATCH. Ceci afin d'éviter une éventuelle perte de donnée non intentionnelle. (https://issues.oasis-open.org/browse/ODATA-274). Cependant, le PUT est conforme au standard dans le cadre d’une mise à jour d'un lien simple

• La récupération de propriété individuelle brute (Raw value) par ajout d'un $value à la fin d'une URL, n'est pas supportée.

• Les opérations batch ne sont pas supportées.