ipnoos

Version : 1.0

Contact : david@soulayrol.name

Chemin : /ipnoos/v1

Licence : CC-BY-NC-SA-4.0

Sommaire

• Description
• Méthodes
• Modèles

ipnoos est une Interface Publique de nooSFere. Il s'agit d'une interface d'inspiration REST.

Choix de conception

Une large partie de l'interface expose le contenu de la base de données comme un ensemble de collections ; par exemple les auteurs, les livres, les éditeurs ou encore les adhérents ou les événements recensés sur le site. Ces collections sont toutes présentées présentées de manière homogène. Elles sont paginées, il est possible de les restreindre par différents critères de recherche ou d'en choisir l'ordre de tri. De même, consulter un élément en particulier, le modifier ou en ajouter un nouveau se fait d'une manière similaire d'une collection à l'autre, tant que les opérations ont un sens et sont permises pour l'utilisateur connecté. Au delà de cette base commune, l'interface fournit des fonctions supplémentaires et spécifiques pour, par exemple, extraire des statistiques ou réaliser de manière optimisée une opération particulière.

Les chemins, les paramètres d'URL, les noms et les clefs des entités sont écrits en anglais pour sa concision (en général) et parce que le jeu de caractères nécessaire tient dans l'encodage ASCII, lequel nécessite moins d'attention, dans l'usage des URL en particulier. Toute la documentation, ainsi que les données transitant par l'interface, sont en revanche en français et encodées en UTF-8.

ipnoos utilise autant que possible les entêtes HTTP standards selon l'usage qui est normalisé. Lorsque des informations supplémentaires sont utiles, des entêtes spécifiques sont utilisés en suivant pour cela les recommandations fournies sur cette page.

Parce que l'interface permet des traitements automatisés et l'exploration systématique de la base de données, son utilisation est soumise à une authentification, et donc réservée aux adhérents de l'association.

Authentification

TODO

Utilisation des collections

En accord avec l'architecture REST, les données présentées sous forme de collections se manipulent à l'aide des méthodes (ou verbes) HTTP ; GET, POST, PUT, etc. Chacun de ces verbes s'accompagne d'une sémantique propre (par exemple, lire une donnée, ou modifier une donnée).

Quelle que soit la collection visitée, les opérations décrites ci-après sont stables. La collection visitée est représentée par le terme générique COLLECTION. Il est indiqué les exceptions ou les compléments qui peuvent êtres rencontrés. La documentation complète de chacune de ces opérations se trouve dans la section Méthodes.

Il est à noter que l'ajout ou la modification d'éléments nécessite le plus souvent des droits particuliers. Par ailleurs, la suppression d'un élément est une opération très rare, voire dangereuse sur certaines collections. Elle peut donc être soumise à des contrôles spécifiques, voire ne pas être implémentée du tout.

Lister les éléments

La consultation d'une collection entière est l'opération la plus complète en terme d'options. Elle est réalisée avec la méthode GET sur le chemin racine de la collection visitée.

Toutes les réponses sur une collection entière sont paginées. Les parcourir se fait donc en sélectionnant un numéro de page et une taille de page, puis en envoyant d'autres requêtes pour obtenir la page précédente ou la page suivante si nécessaire.

Dans les exemple ci-dessous, il est d'abord demandé la première page de la collection, avec sa taille par défaut, puis la page 42, puis la première page mais avec une taille de page différente. Enfin, le dernier exmple démontre la possibilité de combiner les deux paramètres.

GET /ipnoos/v1/COLLECTION
GET /ipnoos/v1/COLLECTION?page=42
GET /ipnoos/v1/COLLECTION?size=50
GET /ipnoos/v1/COLLECTION?page=2&size=25

Il est également possible d'utiliser des filtres et choisir l'ordre de tri.

GET /ipnoos/v1/COLLECTION[?[filter[&filter]][sort]]

Consulter un élément

Tous les éléments de collection possèdent un identifiant unique sur la collection. Il est donc possible de demander un élément en spécifiant cet identifiant.

GET /ipnoos/v1/COLLECTION/by-id/ID

Selon la collection, un élément peut posséder un autre identifiant ou groupe de propriétés, unique. L'interface peut alors proposer le moyen d'obtenir un élément selon ces critères. Par exemple, l'adresse de courriel est unique pour chaque adhérent. Aussi, la collection des membres de l'association permet-elle d'obtenir la fiche d'un adhérent par son adresse.

GET /ipnoos/v1/members/by-email/EMAIL

La liste des membres procure d'ailleurs aussi un raccourci pour accéder à la fiche de l'adhérent connecté.

GET /ipnoos/v1/members/self

Ajouter un élément

Pour créer un élément, il faut employer la méthode POST sur cette collection. La création se fait en employant le même format que l'objet JSON obtenu à la consultation. La création nécessite seulement un sous-ensemble de l'ensemble des propriétés disponibles pour l'éléments. L'identifiant unique en particulier n'est jamais requis ; il est choisi par le serveur.

POST /ipnoos/v1/COLLECTION

Modifier un élément

PUT /ipnoos/v1/COLLECTION/by-id/ID

Supprimer un élément

DELETE /ipnoos/v1/COLLECTION/by-id/ID

Modèle de données

Le format utilisé pour les échanges est JSON.

Réponses

Ipnoos-Collection

La valeur de cet entête est une succession de quatre champs qui renseignent sur le format et la taille de la collection visitée. Il est présent sur toutes les réponses paginées.

• page-index : le numéro de page courant.
• page-size : la taille des pages.
• total-elements : le nombre total d'éléments dans la collections.
• total-pages : le nombre total de page.

Exemple :

Ipnoos-Collection: page-index=1; page-size=10; total-pages=3; total-elements=23

Link

Les URL permettant de naviguer rapidement à l'intérieur de la collection. Son contenu est une liste d'URLs tel que définit dans la RFC 8288.

Dans chaque réponse, l'entête comporte le lien qualifié canonical qui fournit l'URL de référence associée au contenu obtenu. Dans le cas d'une réponse paginée, l'entête comporte également les liens first et next qui représentent respectivement l'URL canonique de la page, le lien vers la première et la dernière page de la collection. Selon la page retournée dans la réponse et la taille de la collection, les liens prev et next peuvent aussi être présents pour naviguer vers la page précédente et la suivante.