Version : 1.0
Contact : david@soulayrol.name
Chemin : /ipnoos/v1
Licence : CC-BY-NC-SA-4.0
ipnoos est une Interface Publique de nooSFere. Il s'agit d'une interface d'inspiration REST.
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.
En accord avec l'architecture REST, les données présentées sous forme de
collections se manipulent à l'aide des 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.
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 le verbe 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]]
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 une autre information, ou un groupe d'information unique. L'interface peut alors proposer le moyen d'obtenir un élément selon ces critères. Par exemple :
GET /ipnoos/v1/members/by-email/EMAIL
Lorsqu'un élément est ajouté à une collection, le serveur lui affecte un identifiant unique.
POST /ipnoos/v1/COLLECTION
PUT /ipnoos/v1/COLLECTION/by-id/ID
DELETE /ipnoos/v1/COLLECTION/by-id/ID
Le format utilisé pour les échanges est JSON.
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
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.
post /memberspost /members/{selectorType}/{selectorValue}/subscriptionsdelete /members/{selectorType}/{selectorValue}delete /members/{selectorType}/{selectorValue}/subscriptions/{id}get /members/exportget /members/{selectorType}/{selectorValue}get /membersget /members/selfget /members/{selectorType}/{selectorValue}/subscriptionsput /members/{selectorType}/{selectorValue}put /members/{selectorType}/{selectorValue}/subscriptions/{id}get /authors/by-id/{id}{
"country" : "country",
"lastName" : "lastName",
"sffOnly" : true,
"city" : "city",
"deathCity" : "deathCity",
"created" : "",
"fullName" : "fullName",
"birthCity" : "birthCity",
"birthDate" : "2000-01-23",
"noolink" : "noolink",
"firstName" : "firstName",
"birthArea" : "birthArea",
"name" : "name",
"birthCountry" : "birthCountry",
"deathArea" : "deathArea",
"deathDate" : "2000-01-23",
"comment" : "comment",
"id" : "id",
"dissolved" : "",
"deathCountry" : "deathCountry",
"email" : "email"
}
{
"reason" : "reason"
}
application/jsonget /authorsUn ou plusieurs critères à appliquer sur la recherche afin de la filtrer. Le format général est le suivant. Les critères disponibles dépendent de la collection visée.
?filter=critère:valeur[,critère:valeur[...]]
default: null [ {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
} ]
{
"reason" : "reason"
}
application/jsonpost /membersapplication/json;schema=member-details{
"firstname" : "firstname",
"subscriptions" : [ {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}, {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
} ],
"role" : "MEMBER",
"surname" : "surname",
"description" : "description",
"id" : 0,
"membership" : {
"endDate" : "2000-01-23",
"endMessage" : "endMessage",
"startDate" : "2000-01-23",
"status" : "ACTIVE"
},
"email" : "email",
"lastname" : "lastname"
}
{
"reason" : "reason"
}
application/json;schema=member-detailsapplication/jsonpost /members/{selectorType}/{selectorValue}/subscriptionsapplication/json{
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}
{
"reason" : "reason"
}
application/jsondelete /members/{selectorType}/{selectorValue}{
"reason" : "reason"
}
application/jsondelete /members/{selectorType}/{selectorValue}/subscriptions/{id}{
"reason" : "reason"
}
application/jsonget /members/export/members,
celle-ci ne permet ni pagination ni tri de la réponse. (exportMembers){
"reason" : "reason"
}
text/csvapplication/jsonL'export complet de la table des adhérents. Le résultat est un fichier CSV. Les champs sont, dans cet ordre :
get /members/{selectorType}/{selectorValue}{
"firstname" : "firstname",
"subscriptions" : [ {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}, {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
} ],
"role" : "MEMBER",
"surname" : "surname",
"description" : "description",
"id" : 0,
"membership" : {
"endDate" : "2000-01-23",
"endMessage" : "endMessage",
"startDate" : "2000-01-23",
"status" : "ACTIVE"
},
"email" : "email",
"lastname" : "lastname"
}
{
"reason" : "reason"
}
application/json;schema=member-detailsapplication/jsonget /membersUn ou plusieurs critères à appliquer sur la recherche afin de la filtrer. Le format général est le suivant. Les critères disponibles dépendent de la collection visée.
?filter=critère:valeur[,critère:valeur[...]]
default: null [ {
"firstname" : "firstname",
"surname" : "surname",
"id" : 0,
"lastname" : "lastname"
}, {
"firstname" : "firstname",
"surname" : "surname",
"id" : 0,
"lastname" : "lastname"
}, {
"firstname" : "firstname",
"surname" : "surname",
"id" : 0,
"lastname" : "lastname"
}, {
"firstname" : "firstname",
"surname" : "surname",
"id" : 0,
"lastname" : "lastname"
}, {
"firstname" : "firstname",
"surname" : "surname",
"id" : 0,
"lastname" : "lastname"
} ]
{
"reason" : "reason"
}
application/jsonget /members/self{
"firstname" : "firstname",
"subscriptions" : [ {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}, {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
} ],
"role" : "MEMBER",
"surname" : "surname",
"description" : "description",
"id" : 0,
"membership" : {
"endDate" : "2000-01-23",
"endMessage" : "endMessage",
"startDate" : "2000-01-23",
"status" : "ACTIVE"
},
"email" : "email",
"lastname" : "lastname"
}
{
"reason" : "reason"
}
application/json;schema=member-detailsapplication/jsonget /members/{selectorType}/{selectorValue}/subscriptions[ {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}, {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
} ]
{
"reason" : "reason"
}
application/json;schema=subscription-arrayapplication/jsonput /members/{selectorType}/{selectorValue}application/json{
"firstname" : "firstname",
"subscriptions" : [ {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}, {
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
} ],
"role" : "MEMBER",
"surname" : "surname",
"description" : "description",
"id" : 0,
"membership" : {
"endDate" : "2000-01-23",
"endMessage" : "endMessage",
"startDate" : "2000-01-23",
"status" : "ACTIVE"
},
"email" : "email",
"lastname" : "lastname"
}
{
"reason" : "reason"
}
application/json;schema=member-detailsapplication/jsonput /members/{selectorType}/{selectorValue}/subscriptions/{id}application/json{
"date" : "2000-01-23",
"amount" : 1,
"year" : 5,
"currency" : "EURO",
"id" : 6
}
{
"reason" : "reason"
}
application/jsonget /collections/by-id/{id}{
"sffOnly" : true,
"creationYear" : "",
"name" : "name",
"ended" : true,
"publisher" : {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
},
"comment" : "comment",
"id" : "id",
"endYear" : "",
"noolink" : "noolink",
"youth" : true
}
{
"reason" : "reason"
}
application/jsonget /collectionsUn ou plusieurs critères à appliquer sur la recherche afin de la filtrer. Le format général est le suivant. Les critères disponibles dépendent de la collection visée.
?filter=critère:valeur[,critère:valeur[...]]
default: null [ {
"name" : "name",
"id" : "id"
}, {
"name" : "name",
"id" : "id"
}, {
"name" : "name",
"id" : "id"
}, {
"name" : "name",
"id" : "id"
}, {
"name" : "name",
"id" : "id"
} ]
{
"reason" : "reason"
}
application/jsonget /publishers/by-id/{id}{
"country" : "country",
"website" : "website",
"sffOnly" : true,
"address" : "address",
"city" : "city",
"created" : "",
"noolink" : "noolink",
"name" : "name",
"postCode" : "postCode",
"comment" : "comment",
"id" : "id",
"dissolved" : "",
"email" : "email"
}
{
"reason" : "reason"
}
application/jsonget /publishersUn ou plusieurs critères à appliquer sur la recherche afin de la filtrer. Le format général est le suivant. Les critères disponibles dépendent de la collection visée.
?filter=critère:valeur[,critère:valeur[...]]
default: null [ {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
}, {
"country" : "country",
"city" : "city",
"name" : "name",
"id" : "id"
} ]
{
"reason" : "reason"
}
application/jsonpost /auth/loginapplication/json{
"expired" : true,
"authorities" : [ "authorities", "authorities" ],
"enabled" : true,
"username" : "username",
"token" : "token"
}
{
"reason" : "reason"
}
application/jsonAuthInfo - AuthInfoAuthorDetails - AuthorDetailsAuthorIdentity - AuthorIdentityCollectionDetails - CollectionDetailsCollectionIdentity - CollectionIdentityMemberDetails - MemberDetailsMemberIdentity - MemberIdentityMembership - MembershipPublisherDetails - PublisherDetailsPublisherIdentity - PublisherIdentityRequestError - RequestErrorSessionInfo - SessionInfoSubscriptionDetails - SubscriptionDetailsAuthInfo - AuthInfo| Propriété | Type | Description |
|---|---|---|
| login |
String
|
|
| password |
String
|
AuthorDetails - AuthorDetails| Propriété | Type | Description |
|---|---|---|
| id |
String
|
|
| name |
String
|
|
| city (optional) |
String
|
|
| country (optional) |
String
|
|
| lastName (optional) |
String
|
|
| firstName (optional) |
String
|
|
| fullName (optional) |
String
|
|
| email (optional) |
String
|
|
| comment (optional) |
String
|
|
| birthCity (optional) |
String
|
|
| birthArea (optional) |
String
|
|
| birthCountry (optional) |
String
|
|
| birthDate (optional) |
date
format: date
|
La date de naissance de l'auteur. |
| deathCity (optional) |
String
|
|
| deathArea (optional) |
String
|
|
| deathCountry (optional) |
String
|
|
| deathDate (optional) |
date
format: date
|
La date de décès de l'auteur. |
| noolink (optional) |
String
|
|
| sffOnly (optional) |
Boolean
|
|
| created (optional) |
Integer
|
|
| dissolved (optional) |
Integer
|
AuthorIdentity - AuthorIdentity| Propriété | Type | Description |
|---|---|---|
| id |
String
|
|
| name |
String
|
|
| city (optional) |
String
|
|
| country (optional) |
String
|
CollectionDetails - CollectionDetails| Propriété | Type | Description |
|---|---|---|
| id |
String
|
|
| name |
String
|
|
| comment (optional) |
String
|
|
| ended (optional) |
Boolean
|
|
| publisher (optional) |
PublisherIdentity
|
|
| noolink (optional) |
String
|
|
| sffOnly (optional) |
Boolean
|
|
| creationYear (optional) |
Integer
|
|
| endYear (optional) |
Integer
|
|
| youth (optional) |
Boolean
|
CollectionIdentity - CollectionIdentity| Propriété | Type | Description |
|---|---|---|
| id |
String
|
|
| name |
String
|
MemberDetails - MemberDetails| Propriété | Type | Description |
|---|---|---|
| id (optional) |
Long
format: int64
|
|
| firstname (optional) |
String
|
|
| lastname (optional) |
String
|
|
| surname (optional) |
String
|
|
| description (optional) |
String
|
|
| email (optional) |
String
|
|
| membership (optional) |
Membership
|
|
| role (optional) |
String
Enum:
|
|
| subscriptions (optional) |
array[SubscriptionDetails]
|
MemberIdentity - MemberIdentity| Propriété | Type | Description |
|---|---|---|
| id (optional) |
Long
format: int64
|
|
| firstname (optional) |
String
|
|
| lastname (optional) |
String
|
|
| surname (optional) |
String
|
Membership - Membership| Propriété | Type | Description |
|---|---|---|
| status (optional) |
String
Enum:
|
|
| startDate (optional) |
date
format: date
|
|
| endDate (optional) |
date
format: date
|
|
| endMessage (optional) |
String
|
PublisherDetails - PublisherDetails| Propriété | Type | Description |
|---|---|---|
| id |
String
|
|
| name |
String
|
|
| city (optional) |
String
|
|
| country (optional) |
String
|
|
| address (optional) |
String
|
|
| postCode (optional) |
String
|
|
| email (optional) |
String
|
|
| website (optional) |
String
|
|
| noolink (optional) |
String
|
|
| comment (optional) |
String
|
|
| sffOnly (optional) |
Boolean
|
|
| created (optional) |
Integer
|
|
| dissolved (optional) |
Integer
|
PublisherIdentity - PublisherIdentity| Propriété | Type | Description |
|---|---|---|
| id |
String
|
|
| name |
String
|
|
| city (optional) |
String
|
|
| country (optional) |
String
|
RequestError - RequestError| Propriété | Type | Description |
|---|---|---|
| reason (optional) |
String
|
SessionInfo - SessionInfo| Propriété | Type | Description |
|---|---|---|
| username |
String
|
|
| authorities (optional) |
array[String]
|
|
| enabled (optional) |
Boolean
|
|
| expired (optional) |
Boolean
|
|
| token |
String
|
SubscriptionDetails - SubscriptionDetailsLa représentation d'une cotisation.
| Propriété | Type | Description |
|---|---|---|
| id (optional) |
Long
format: int64
|
|
| amount (optional) |
Integer
|
Le montant de la cotisation. |
| currency (optional) |
String
Enum:
|
La monnaie qualifiant le montant de la cotisation. Seul l'EURO est supporté aujourd'hui. |
| date (optional) |
date
format: date
|
La date de paiement de la cotisation. |
| year (optional) |
Integer
|
L'année couverte par la cotisation. |