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

API Mir@bel

Web-service REST pour interroger Mir@bel.
  • v1.1.5 (nov 2020) Corrige un bug sur /acces concernant les abonnements par collections.
  • v1.1.4 (sept 2020) Les critères lacunaire et selection sont booléens. Le texte recherché doit contenir 3 caractères au minimum.
  • v1.1.3 (juil 2020) Ajout de l'identifiant bnfark. Autorise /titres et /mes/titres sans filtre. Les ISSN de titre étaient absents des titres de /revues. Corrections mineures.
  • v1.1.2 (nov 2019) Ajout de Acces.url_proxy quand pertinent. Acces.url pointe sur sa ressource à défaut d'URL spécifique. Ajout de Acces.lacunaire et Acces.selection.
  • v1.1.0 (nov 2019) Remplacement du critère "lien=possession" par "possession=1". Ajout du critère "abonnement=1". Ajout de nombreux champs dans les données renvoyées.
  • v1.0.0 (mai 2019) Première version publique.
Version 1.1.5

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é" au lieu de "restreint".

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
actif

Restreindre aux titres actifs. Autrement dit, exclure les anciens titres des revues, ceux qui ont des successeurs.

queryNonboolean
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é" au lieu de "restreint". Il doit aussi être donné pour utiliser les critères "possession" et "abonnement".

queryNonstring
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
possession

Si possession=1, seuls les titres possédés par le partenaire seront concernés. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
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 titres 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. Le premier titre est le titre actif.

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'une revue et de ses titres

{ → Revue }
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", ou /titres pour l'ensemble des titres. Les titres sont triés alphabétiquement, hors préfixes.

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

Restreindre aux titres actifs. Autrement dit, exclure les anciens titres des revues, ceux qui ont des successeurs.

queryNonboolean
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
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
possession

Si possession=1 et abonnement=0, seuls les titres possédés par le partenaire seront concernés. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
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
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
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
possession

Si possession=1, seuls les titres possédés par le partenaire seront concernés. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
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
abonnement

Restreint la liste aux titres auxquels le partenaire est abonné, via une collection ou une ressource. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
possession

Si possession=1, seuls les titres possédés par le partenaire seront concernés. Les critères "abonnement" et "possession" sont cumulables (OU logique).

queryNonboolean
ressourceid

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

queryNoninteger
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.
issn[ string ]
La liste des ISSN des titres de cet accès en ligne. Champ présent seulement si la recherche se fait par ISSN.
lacunaireboolean
Si vrai, des numéros sont manquants sur la période, donc la couverture n'est pas exhaustive.
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.
selectionboolean
Si vrai, un numéro est représenté par une sélection d'articles, donc la couverture n'est pas exhaustive.
titreidinteger
référence à Titre.id
urlstring
URL de la revue.
urlproxystring
Si le partenaire est déclaré et que ses proxys sont actifs pour cet accès, alors ce champ contient l'URL avec application des proxys. Sinon, ce champ n'est pas présent.
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.

bnfarkstring
Identifiant Ark de la BNF.
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
Si true, la notice du Sudoc n'est pas localisée.
sudocppnstring
Identifiant PPN du Sudoc.
supportstring
Valeur parmi "inconnu", "papier", "electronique"
worldcatocninteger
Identifiant OCN de Worldcat.

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.
liens[ string ]
Liste d'URL extérieures (Facebook, Twitter, etc) pour ce titre.
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.