Télécharger la description au format OpenApi JSON ou YAML

API Mir@bel

Web-service REST pour interroger Mir@bel.

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.

Les versions futures de cette API resteront compatibles avec les versions 1.* précédentes. Donc une requête pour la version actuelle de l'API restera valable dans le futur, avec une réponse éventuellement enrichie de champs supplémentaires.

v1.2.1 (fév 2023) Les chemins /editeurs/{id} /revues/{id} et /titres/{id} gèrent les redirections
v1.2.0 (juin 2022) Ajout d'informations sur les éditeurs, par une extension des données du modèle Titre et la création de points d'entrée /editeurs. Le champ Titre.editeurs ne liste plus que les éditeurs actuels.
v1.1.6 (fév 2022) La documentation nommait "datebarriereinfo" un champ disponible sous le nom "dateinfo".
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.2.1

Licence des données

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

Contact

Nom: Mir@bel
URL: https://reseau-mirabel.info/site/contact

Mir@bel : https://reseau-mirabel.info/site/contact

Format des réponses

Les réponses de l'API sont au format JSON.

Liste des chemins

/acces/revue GET Liste des accès sur une revue
/acces/titres GET Liste des accès sur une sélection de titres
/editeurs/{id} GET Détail d'un éditeur identifié par son ID Mir@bel
/editeurs/idref/{idref} GET Détail d'un éditeur cherché par son IdRef
/revues/{id} GET Détail d'une revue
/titres/{id} GET Détail d'un titre
/titres GET Liste de titres recherchés par différents critères
/mes/acces GET Pour un partenaire de Mir@bel, liste des accès sur ses revues
/mes/acces/changes GET Pour un partenaire de Mir@bel, liste des modifications d'accès sur ses revues
/mes/titres GET Pour un partenaire de Mir@bel, liste des titres, par possession ou abonnement

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 /acces/revue

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
issn	Numéro ISSN (ou ISSN-e) de la forme XXXX-XXXX	query	Non	string
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".	query	Non	string
revueid	Identifiant numérique de la revue dans Mir@bel.	query	Non	integer
sudoc	Identifiant PPN de SUDOC.	query	Non	string
worldcat	Identifiant numérique de Worldcat.	query	Non	integer

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 /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.	query	Non	boolean
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.	query	Non	integer
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.	query	Non	string
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".	query	Non	string
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).	query	Non	boolean
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).	query	Non	boolean
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.	query	Non	integer
sudoc	Identifiant PPN de SUDOC.	query	Non	string
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").	query	Non	string
worldcat	Identifiant numérique OCN de Worldcat, ou liste d'identifiants joints par des virgules.	query	Non	integer

Réponses

Code HTTP	Description	Schema
200	liste d'accès	[ → Acces ]
default	Erreur	→ Erreur

/editeurs/{id}

GET /editeurs/{id}

Titre

Détail d'un éditeur identifié par son ID Mir@bel

Description

Les infos que Mir@bel fournit sur un éditeur identifié par son ID dans Mir@bel ou par son IdRef.

Par exemple, /editeurs/64 pour décrire l'éditeur qui a l'identifiant 64 dans Mir@bel.

URL

GET /editeurs/{id}

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
id	Identifiant numérique de l'éditeur (ID interne à Mir@bel).	path	Oui	string

Réponses

Code HTTP	Description	Schema
200	Détail d'un éditeur	{ `editeur`: → Editeur , `relations_titres`: [ → EditeurTitre ] }
301	Redirection	→ Redirection
default	Erreur	→ Erreur

/editeurs/idref/{idref}

GET /editeurs/idref/{idref}

Titre

Détail d'un éditeur cherché par son IdRef

Description

Par exemple, /editeurs/idref/029524989.

URL

GET /editeurs/idref/{idref}

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
idref	Identifiant IdRef de l'éditeur, de type PPN (8 chiffres suivis d'un chiffre ou de "X").	path	Oui	string

Réponses

Code HTTP	Description	Schema
200	Détail d'un éditeur	{ `editeur`: → Editeur , `relations_titres`: [ → EditeurTitre ] }
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 /revues/{id}

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
id	Identifiant numérique de la revue.	path	Oui	integer

Réponses

Code HTTP	Description	Schema
200	Détail d'une revue et de ses titres	{ `revue`: → Revue }
301	Redirection	→ Redirection
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 /titres/{id}

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
id	Identifiant numérique du titre.	path	Oui	integer

Réponses

Code HTTP	Description	Schema
200	Détail d'un titre	→ Titre
301	Redirection	→ Redirection
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 /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.	query	Non	boolean
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.	query	Non	integer
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.	query	Non	string
offset	Les réponses sont limitées à 1000 titres. Si cette limite est atteinte, ce paramètre permet de demander la suite.	query	Non	integer
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.	query	Non	integer
sudoc	Identifiant PPN de SUDOC.	query	Non	string
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").	query	Non	string
worldcat	Identifiant numérique OCN de Worldcat, ou liste d'identifiants joints par des virgules.	query	Non	integer

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 /mes/acces

Paramètres

Nom

Description

Lieu

Requis ?

Type, format

partenaire

Clé privée du partenaire

query

Oui

string

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).

query

Non

boolean

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).

query

Non

boolean

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 /mes/acces/changes

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
partenaire	Clé privée du partenaire	query	Oui	string
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).	query	Non	boolean
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ë.	query	Oui	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).	query	Non	boolean

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 /mes/titres

Paramètres

Nom	Description	Lieu	Requis ?	Type, format
partenaire	Clé privée du partenaire	query	Oui	string
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).	query	Non	boolean
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).	query	Non	boolean
ressourceid	Identifiant numérique d'une ressource de Mir@bel (par ex. `3` pour Cairn.info). Filtre supplémentaire	query	Non	integer

Réponses

Code HTTP	Description	Schema
200	liste de titres	[ → Titre ]
default	Erreur	→ Erreur

Modèles de données

Acces

id	integer Identifiant unique attribué par Mir@bel à cet accès en ligne.
contenu	string Parmi "Intégral", "Résumé", "Sommaire", "Indexation".
collections	[ string ] Nom des éventuelles collections concernées, dans la ressource de cet accès.
datedebut	string Date (YYYY ou YYYY-mm ou YYYY-mm-dd) de début d'accès.
datefin	string Éventuelle date (YYYY ou YYYY-mm ou YYYY-mm-dd) de fin d'accès.
dateinfo	string Description textuelle de la date barrière. Si cette donnée n'est pas fournie par la source de l'accès, elle est déduite du champ 'embargoinfo'. Exemple de valeur : "Accès avant une date barrière mobile de 3 années calendaires".
dernumurl	string URL pointant sur le dernier numéro de la revue.
diffusion	string Valeur parmi "libre", "restreint", "abonné". Cette dernière valeur n'est possible que si le paramètre "partenaire" est présent.
embargoinfo	string Le contenu du champ `embargo_info`, si l'accès a été créé par un import KBART.
identifiantpartenaire	string 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.
lacunaire	boolean Si vrai, des numéros sont manquants sur la période, donc la couverture n'est pas exhaustive.
mailurl	string URL de la revue par alerte courriel.
nodebut	integer Null ou numérotation initiale, par exemple 6.
nofin	integer Null ou numérotation finale, par exemple 12.
numerodebut	string Intitulé du numéro initial, par exemple "Vol. I, no 6".
numerofin	string Intitulé du numéro final, par exemple "Vol. XXV, no 12 (HS)".
ressource	string Nom de la ressource fournissant cet accès.
ressourceid	integer Identifiant unique attribué par Mir@bel à la ressource de cet accès.
rssurl	string URL du flux RSS de la revue.
selection	boolean Si vrai, un numéro est représenté par une sélection d'articles, donc la couverture n'est pas exhaustive.
titreid	integer référence à Titre.id
url	string URL de la revue.
urlproxy	string 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.
voldebut	integer Null, ou volume initial, par exemple 1.
volfin	integer Null, ou volume final, par exemple 25.

AccesChanges

Trois champs. creations et modifications sont des listes d'accès. Et 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.

Editeur

id	integer Identifiant unique attribué par Mir@bel à cet éditeur.
identifiants	[ ] Liste d'identifiants sous forme de couples [clé, valeur], par exemple `[["idref", "029524989"]]`.
liens	[ string ] Liste d'URL extérieures (Facebook, Twitter, etc) pour cet éditeur.
nom	string Nom (sans son éventuel préfixe comme "L'").
pays	string Codes ISO à 3 lettres du pays de l'éditeur.
prefixe	string Préfixe du nom de l'éditeur (par exemple "L'").
role	string Rôle général de l'éditeur pour ses titres.
url	string Site web de l'éditeur. URL publique, hors Mir@bel.
url_mirabel	string Page web de cet éditeur sur le site de Mir@bel.

EditeurTitre

Les champs editeur* sont absents si la relation se rapporte à un éditeur connu. De même pour titre*.

editeur	string Nom de l'éditeur (sans son éventuel préfixe comme "L'").
editeur_id	integer Identifiant unique attribué par Mir@bel à cet éditeur.
precedent	boolean Il s'agit d'un éditeur précédent, qui n'intervient plus sur ce titre.
role	string Rôle de l'éditeur spécifiquement pour ce titre.
titre	string Titre (sans son éventuel préfixe comme "L'").
titre_id	integer Identifiant unique attribué par Mir@bel à ce titre.

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.

bnfark	string Identifiant Ark de la BNF.
issn	string 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.
issnl	string Éventuellemnt absent.
statut	string Valeur parmi "en cours", "sans", "valide"
sudocnoholding	boolean Si true, la notice du Sudoc n'est pas localisée.
sudocppn	string Identifiant PPN du Sudoc.
support	string Valeur parmi "inconnu", "papier", "electronique"
worldcatocn	integer Identifiant OCN de Worldcat.

Revue

id	integer Identifiant unique attribué par Mir@bel à cette revue.
dermodif	integer Timestamp (secondes) de la dernière modification de la revue (incluant titres et accès).
derverif	integer 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

id	integer Identifiant unique attribué par Mir@bel à ce titre.
bouquetpartenaire	string 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.
datedebut	string, date Date de début de ce titre.
datefin	string, date Éventellement, date de fin de ce titre.
editeurs	[ string ] Liste des noms d'éditeurs actuels. Voir `relations_editeurs` pour une liste plus détaillée.
identifiantpartenaire	string 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.
obsoletepar	integer Éventuel identifiant numérique du titre qui a remplacé celui-ci dans la revue.
periodicite	string Périodicité.
prefixe	string Préfixe du titre (par exemple "L'").
relations_editeurs	[ → EditeurTitre ] Ce champ n'est présent que dans les requêtes cherchant un titre unique, autrement dit /titres/{id}.
revueid	integer Identifiant unique attribué par Mir@bel à cette revue (historique de titres).
titre	string Titre (sans son éventuel préfixe comme "L'").
url	string Site web de la revue. URL publique, hors Mir@bel.
url_revue_mirabel	string Page web de la revue sur le site de Mir@bel.

Erreur

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

Redirection

code	integer, int32 Code HTTP de la redirection (300 à 399)
nouvelid	integer, int32 identifiant de l'objet après redirection
url	string url de l'objet après redirection