Télécharger la description au format OpenApi JSON (Swagger)

API Mir@bel

Web-service REST pour interroger Mir@bel
Version 1.0.0

Données sous Licence Ouverte, compatible ODC-BY et CC-BY 2.0. Réutilisation possible des données à condition d'en mentionner l'origine.

Licence des données

Licence ouverte : https://www.etalab.gouv.fr/licence-ouverte-open-licence

Format des réponses

Les réponses de l'API sont au format JSON. Le format XML pourrait être ajouté, à la demande.

Liste des chemins

Tous les chemins doivent être préfixés par /api.

Détail des actions

/acces/revue

GET /acces/revue

Titre
Liste des accès sur une revue
Description

Liste tous les accès sur une revue (qui peut regrouper plusieurs titres si l'historique de la revue est complexe). La revue est identifiée par son ID dans Mir@bel, ou un ISSN, un numéro OCLC de Worldcat, etc. Au moins un critère est nécessaire. Par exemple, /acces/revue?issn=1169-1018 montrera les accès en ligne pour la revue "Population (english edition)" dont l'ancien titre a cet ISSN.

URL
GET /api/acces/revue
Paramètres
Nom Description Lieu Requis ? Type, format
issn

Numéro ISSN (ou ISSN-e) de la forme XXXX-XXXX

queryNonstring
partenaire

Clé privée du partenaire. Si ce paramètre est fourni, les accès en ligne pourront avoir une diffusion "abonné".

queryNonstring
revueid

Identifiant numérique de la revue dans Mir@bel.

queryNoninteger
sudoc

Identifiant PPN de SUDOC.

queryNonstring
worldcat

Identifiant numérique de Worldcat.

queryNoninteger
Réponses
Code HTTP Description Schema
200

liste d'accès

[ → Acces ]
default

Erreur

Erreur

/acces/titres

GET /acces/titres

Titre
Liste des accès sur une sélection de titres
Description

Liste tous les accès sur des titres de revue (qui peuvent différer de la revue s'il y a un historique de titres). Chaque titre est identifié par son ID dans Mir@bel, ou un ISSN, un numéro OCLC de Worldcat, etc. Au moins un critère est nécessaire. Par exemple, /acces/titres?issn=1169-1018 montrera les accès en ligne pour le titre "Population (english selection)" qui a cet ISSN.

Les critères de recherche sont les mêmes que pour /titres.

URL
GET /api/acces/titres
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique du titre dans Mir@bel. Il est aussi possible de donner une liste de nombres séparés par des virgules, par exemple id=14,72,1044 pour sélectionner les accès de ces trois titres.

queryNoninteger
issn

Numéro ISSN (ou ISSN-e ou ISSN-l) de la forme XXXX-XXXX. Une liste d'ISSN est possible, par exemple issn=1660-7880,1776-8098.

queryNonstring
partenaire

Clé privée du partenaire. Si ce paramètre est fourni, les accès en ligne pourront avoir une diffusion "abonné".

queryNonstring
revueid

Identifiant numérique de la revue dans Mir@bel, ou liste avec des virgules comme séparateurs. Si ce critère est présent, les titres seront ordonnés du plus récent au plus ancien, pour rendre l'historique de titre de la revue plus lisible.

queryNoninteger
sudoc

Identifiant PPN de SUDOC.

queryNonstring
titre

Titre. Le préfixe sera ignoré ("Monde" ou "Le Monde" donne le même résultat). Une recherche en début ("Monde%") ou milieu de titre ("%monde%") est possible. Une recherche exacte portera aussi sur le sigle des titres (par exemple, "titre=AJDA").

queryNonstring
worldcat

Identifiant numérique OCN de Worldcat, ou liste d'identifiants joints par des virgules.

queryNoninteger
Réponses
Code HTTP Description Schema
200

liste d'accès

[ → Acces ]
default

Erreur

Erreur

/revues/{id}

GET /revues/{id}

Titre
Détail d'une revue
Description

Pour éviter une requête supplémentaire, l'historique des titre de la revue est aussi fourni, en commençant par le plus récent. Par exemple, /revues/3221 montrera les dates de dernière modification et de vérification de la revue, ainsi que son historique de titres.

URL
GET /api/revues/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique de la revue.

pathNoninteger
Réponses
Code HTTP Description Schema
200

Détail d'un titre (le dernier de la revue)

{ → Titre }
default

Erreur

Erreur

/titres/{id}

GET /titres/{id}

Titre
Détail d'un titre
Description

Les infos que Mir@bel fournit sur un titre par son ID dans Mir@bel. Par exemple, /titres/14 pour trouver le titre qui a l'identifiant 14 dans Mir@bel.

URL
GET /api/titres/{id}
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique du titre.

pathNoninteger
Réponses
Code HTTP Description Schema
200

Détail d'un titre

{ → Titre }
default

Erreur

Erreur

/titres

GET /titres

Titre
Liste de titres recherchés par différents critères
Description

Liste les titres correspondant aux critères de recherche. Donner au moins un paramètre dans la requête pour sélectionner le titre. Par exemple, /titres?issn=1660-7880 pour trouver le titre qui a l'ISSN 1660-7880, ou /titres?titre=%monde% pour lister les titres contenant "Monde". Les titres sont triés alphabétiquement, hors préfixes.

URL
GET /api/titres
Paramètres
Nom Description Lieu Requis ? Type, format
id

Identifiant numérique du titre dans Mir@bel. Il est aussi possible de donner une liste de nombres séparés par des virgules, par exemple id=14,72,1044 pour sélectionner ces trois titres.

queryNoninteger
revueid

Identifiant numérique de la revue dans Mir@bel, ou liste avec des virgules comme séparateurs. Si ce critère est présent, les titres seront ordonnés du plus récent au plus ancien, pour rendre l'historique de titre de la revue plus lisible.

queryNoninteger
issn

Numéro ISSN (ou ISSN-e ou ISSN-l) de la forme XXXX-XXXX. Une liste d'ISSN est possible, par exemple issn=1660-7880,1776-8098.

queryNonstring
worldcat

Identifiant numérique OCN de Worldcat, ou liste d'identifiants joints par des virgules.

queryNoninteger
sudoc

Identifiant PPN de SUDOC.

queryNonstring
titre

Titre. Le préfixe sera ignoré ("Monde" ou "Le Monde" donne le même résultat). Une recherche en début ("Monde%") ou milieu de titre ("%monde%") est possible. Une recherche exacte portera aussi sur le sigle des titres (par exemple, "titre=AJDA").

queryNonstring
Réponses
Code HTTP Description Schema
200

Liste de titres

[ → Titre ]
default

Erreur

Erreur

/mes/acces

GET /mes/acces

Titre
Pour un partenaire de Mir@bel, liste des accès sur ses revues
Description

Liste de tous les accès sur les revues du partenaire, sélectionnées par possession ou abonnement. L'accès est restreint aux partenaires de Mir@bel.

URL
GET /api/mes/acces
Paramètres
Nom Description Lieu Requis ? Type, format
partenaire

Clé privée du partenaire

queryOuistring
lien

"possession" ou "abonnement". Restreint la liste aux revues possédées ou liées par abonnement. Attention, "abonnement" n'est pas encore implémenté.

queryNonstring
Réponses
Code HTTP Description Schema
200

liste d'accès

[ → Acces ]

/mes/acces/changes

GET /mes/acces/changes

Titre
Pour un partenaire de Mir@bel, liste des modifications d'accès sur ses revues
Description

Liste les ajouts, modifications et suppressions concernant les accès des revues du partenaire, sélectionnées par possession ou abonnement. L'accès est restreint aux partenaires de Mir@bel.

URL
GET /api/mes/acces/changes
Paramètres
Nom Description Lieu Requis ? Type, format
partenaire

Clé privée du partenaire

queryOuistring
depuis

Timestamp (en secondes) à partir duquel lister les changements. Une date textuelle ("2019-01-20 12:30:00" ou "-1 week") est aussi possible, mais plus ambiguë.

queryOuiinteger|string
lien

"possession" ou "abonnement". Restreint la liste aux titres possédés ou liés par abonnement. Par défaut, liste les possessions. Attention, "abonnement" n'est pas encore implémenté.

queryNonstring
Réponses
Code HTTP Description Schema
200

Objet décrivant les ajouts, modifications, suppressions

AccesChanges

/mes/titres

GET /mes/titres

Titre
Pour un partenaire de Mir@bel, liste des titres, par possession ou abonnement
Description

Liste des titres de revues possédées par un partenaire de Mir@bel, et décrites par leur dernier titre. L'accès est restreint aux partenaires de Mir@bel.

URL
GET /api/mes/titres
Paramètres
Nom Description Lieu Requis ? Type, format
partenaire

Clé privée du partenaire

queryOuistring
ressourceid

Identifiant numérique d'une ressource de Mir@bel (par ex. 3 pour Cairn.info). Filtre supplémentaire

queryNoninteger
lien

"possession" ou "abonnement". Restreint la liste aux titres possédés ou liés par abonnement. Par défaut, liste les possessions. Attention, "abonnement" n'est pas encore implémenté.

queryNonstring
Réponses
Code HTTP Description Schema
200

liste de titres

[ → Titre ]
default

Erreur

Erreur

Modèles de données

Acces

idinteger
Identifiant unique attribué par Mir@bel à cet accès en ligne.
contenustring
Intégral, Résumé, Sommaire, Indexation
collections[ ]
Nom des éventuelles collections concernées, dans la ressource de cet accès.
datedebutstring
Date (YYYY ou YYYY-mm ou YYYY-mm-dd) de début d'accès.
datefinstring
Éventuelle date (YYYY ou YYYY-mm ou YYYY-mm-dd) de fin d'accès.
datebarriereinfostring
Description de la date barrière.
dernumurlstring
URL pointant sur le dernier numéro de la revue.
diffusionstring
Valeur parmi "libre", "restreint", "abonné". Cette dernière valeur n'est possible que si le paramètre "partenaire" est présent.
embargoinfostring
Le contenu du champ `embargo_info`, si l'accès a été créé par un import KBART.
identifiantpartenairestring
Si interrogation sur les possessions d'un partenaire, donne l'identifiant de possession.
mailurlstring
URL de la revue par alerte courriel.
nodebutinteger
Null ou numérotation initiale, par exemple 6.
nofininteger
Null ou numérotation finale, par exemple 12.
numerodebutstring
Intitulé du numéro initial, par exemple "Vol. I, no 6".
numerofinstring
Intitulé du numéro final, par exemple "Vol. XXV, no 12 (HS)".
ressourcestring
Nom de la ressource fournissant cet accès.
ressourceidinteger
Identifiant unique attribué par Mir@bel à la ressource de cet accès.
rssurlstring
URL du flux RSS de la revue.
titreidinteger
référence à Titre.id
urlstring
URL de la revue.
voldebutinteger
Null, ou volume initial, par exemple 1.
volfininteger
Null, ou volume final, par exemple 25.

AccesChanges

Trois champs. "creations" et "modifications" sont des listes d'accès. "suppressions" est une liste des ID d'accès supprimés (non-limitée aux revues possédées).

creations[ → Acces ]
Liste des accès ajoutés.
modifications[ → Acces ]
suppressions[ integer ]
Identifiants (cf Acces.id) des accès supprimés.

Issn

Attributs identifiant un titre ou une revue. Cette structure contient généralement un ISSN, mais peut aussi ne donner que d'autres identifiants.

issnstring
Ce champ sera absent si l'ISSN n'existe pas ou n'est pas connu, mais qu'un PPN (SUDOC) ou qu'un OCN (Worldcat) existe.
issnlstring
Éventuellemnt absent.
statutstring
Valeur parmi "en cours", "sans", "valide"
sudocnoholdingboolean
sudocppnstring
supportstring
Valeur parmi "inconnu", "papier", "electronique"
worldcatocninteger

Revue

idinteger
Identifiant unique attribué par Mir@bel à cette revue.
dermodifinteger
Timestamp (secondes) de la dernière modification de la revue (incluant titres et accès).
derverifinteger
Timestamp (secondes) de la dernière vérification des données de la revue (incluant titres et accès) dans Mir@bel.
titres[ → Titre ]
Historique des titres de la revue, triés du plus récent au plus ancient. | Le premier est donc le titre actif.

Titre

idinteger
Identifiant unique attribué par Mir@bel à ce titre.
bouquetpartenairestring
Ce champ est présent si le titre a été produit par une recherche sur les possessions, par exemple dans la requête /mes/titres. Il contient le bouquet déclaré par le partenaire pour ce titre dans ses possessions.
datedebutstring, date
Date de début de ce titre.
datefinstring, date
Éventellement, date de fin de ce titre.
editeurs[ string ]
Liste des noms noms d'éditeurs.
identifiantpartenairestring
Ce champ est présent si le titre a été produit par une recherche sur les possessions, par exemple dans la requête /mes/titres. Il contient l'identification local au partenaire pour ce titre, telle que déclaré dans ses possessions.
issns[ → Issn ]
Liste des identifiants, notamment ISSN, attachés au titre.
langues[ string ]
Liste des langues de ce titre, par leurs codes ISO à 3 lettres.
obsoleteparinteger
Éventuel identifiant numérique du titre qui a remplacé celui-ci dans la revue.
periodicitestring
Périodicité.
prefixestring
Préfixe du titre (par exemple "L'").
revueidinteger
Identifiant unique attribué par Mir@bel à cette revue (historique de titres).
titrestring
Titre (sans son éventuel préfixe comme "L'").
urlstring
Site web de la revue. URL publique, hors Mir@bel.
url_revue_mirabelstring
Page web de la revue sur le site de Mir@bel.

Erreur

codeinteger, int32
Code HTTP de l'erreur
messagestring
Description détaillée du problème
fieldsstring
Éventuels champs créant un trouble dans la requête
details?
Éventuels détails sur l'erreur.