2. Créé en 2000
Mission
fournir à la communauté de l’ESR
des outils pour l’archivage, la
diffusion et la valorisation des
publications et des données
scientifiques.
Basé à Villeurbanne
16 personnes
Partenaire de projets européens :
MedOANet, DARIAH-EU, PEER
Equipex DILOH, ANR Campus AAR
https://www.ccsd.cnrs.fr/
https://hal.archives-ouvertes.fr
L'archive ouverte pluridisciplinaire HAL,
est destinée au dépôt et à la diffusion
d'articles scientifiques de niveau
recherche, publiés ou non, et de thèses.
https://www.sciencesconf.org
Plateforme Web ouverte aux
organisateurs de colloques, workshops
ou réunions scientifiques
https://episciences.org
Plateforme de revues électroniques en
libre accès, alimentées par les articles
déposés dans les archives ouvertes
3. Plan
• Introduction
• Accès aux référentiels
• Les référentiels pour le dépôt SWORD
• Les référentiels AURéHAL
• L’API de recherche d’affiliations
• Accès aux documents de l’archive HAL
• Les points d’entrées
• Les paramètres
• Les facettes
• Mise en pratique
• Dépôt SWORD
5. Les types d’API disponibles
Référentiels
Accès aux
référentiels
AuréHAL
Documents
Accès aux
ressources
de HAL
Import
Dépôt via
protocole
SWORD
Moissonnage
Accès aux
ressources
de HAL via
protocole
OAI-PMH
Triplestore
(09/17)
Accès aux
données
RDF
https://api.archives-ouvertes.fr
6. Les types d’API disponibles
Référentiels
Accès aux
référentiels
AuréHAL
Documents
Accès aux
ressources
de HAL
Import
Dépôt via
protocole
SWORD
Moissonnage
Accès aux
ressources
de HAL via
protocole
OAI-PMH
Triplestore
(09/17)
Accès aux
données
RDF
https://api.archives-ouvertes.fr
7. Les types d’API disponibles
Référentiels
Accès aux
référentiels
AuréHAL
Documents
Accès aux
ressources
de HAL
Import
Dépôt via
protocole
SWORD
Moissonnage
Accès aux
ressources
de HAL via
protocole
OAI-PMH
Triplestore
(09/17)
Accès aux
données
RDF
https://api.archives-ouvertes.fr
9. Syntaxe d’une Requête API web
URL dans le navigateur
Point d’accès https://api.archives-ouvertes.fr/search/hal
Séparateur paramètres ?
paramètre = valeur q=*
paramètres séparés par &
Exemples :
https://api.archives-ouvertes.fr/search/hal?q=*
https://api.archives-ouvertes.fr/search/hal?q=*&rows=5
https://api.archives-ouvertes.fr/search/hal?q=*&rows=5&wt=xml
https://api.archives-ouvertes.fr/search/hal?q=*&start=20&rows=5&wt=xml
15. Le dépôt SWORD
• API REST
https://api.archives-ouvertes.fr/docs/sword
• Dépôt d’un fichier au format XML-TEI
• Dans un portail HAL : portail HAL générique ou portail
institutionnel HAL INRIA, HAL Univ Lorraine, …
• Un type de dépôt : Article, Communication, Image,
Vidéo, …
• Une liste de métadonnées requises
• Des valeurs prédéfinies pour certaines métadonnées
17. Les types de documents
• Liste des types de documents acceptés sur HAL
• Dépend du portail hal
• Documentation
https://api.archives-ouvertes.fr/docs/ref/resource/doctype
• Exemple
• Types de document acceptés sur TEL ( instance_s=tel ) :
https://api.archives-ouvertes.fr/ref/doctype?instance_s=tel
18. Liste des métadonnées
• Permet d’obtenir la liste des métadonnées requises
pour un type de document et dans un portail
• Exemples :
• Liste des métadonnées pour le dépôt d’un article dans le
portail de l’université de Lorraine :
https://api.archives-ouvertes.fr/ref/metadata/?instance_s=univ-
lorraine&docType_s=ART&wt=xml
• Liste des métadonnées pour le dépôt d’un mémoire dans
le portail de Inria :
https://api.archives-
ouvertes.fr/ref/metadata/?instance_s=inria&docType_s=MEM&wt=json
21. Les référentiels AURéHAL
• Accès aux référentiels utilisés dans l’archive ouverte
HAL : https://aurehal.archives-ouvertes.fr
• Gestion des référentiels Auteurs, Structures,
Domaines scientifiques, revues, projets ANR et
projets européens
35. Recherche d’affiliations d’un auteur
• Algorithme permettant de retrouver une affiliation d’un
auteur
• Prend en compte le nom, prénom, adresse mail et la date de
publication
• Basé sur les affiliations existantes dans HAL
• Documentation
https://api.archives-ouvertes.fr/docs/ref/resource/authorstructure
• Exemple
https://api.archives-
ouvertes.fr/search/authorstructure/?firstName_t=laurent&las
tName_t=capelli&wt=xml
• Evolution de l’algorithme en prenant en compte le
laboratoire (string)
37. Contenu API des documents
• Tous les dépôts de HAL en ligne
• +/- toutes les métadonnées d’un dépôt sous
différentes formes
• + version des métadonnées aux formats :
• Bibtex
• XML-TEI
• COinS (ContextObjects in Spans)
• Endnote
• Texte intégral indexé mais pas stocké
39. Entrée par un portail
• Point d’entrée pour un portail :
https://api.archives-ouvertes.fr/search/<instance>
• Exemple :
https://api.archives-ouvertes.fr/search/univ-lorraine/
• NB : Dans le cas d’un portail/instance, si un dépôt a
plusieurs versions, on ne trouve que la dernière.
40. Entrée par une collection
• Point d’entrée pour une collection:
https://api.archives-ouvertes.fr/search/<COLLECTION>
• Exemple :
https://api.archives-ouvertes.fr/search/LORIA
• NB : Dans le cas d’une collection, si un dépôt a
plusieurs versions, on ne trouve que la version
tamponnée.
41. Paramètres utiles
Nom paramètre/usage Description exemple Valeur par
défaut
q Requête de recherche q=exemple * :*
Chercher dans un champ NomDuChamp:valeur q=title_t:test
q=title_t:(printemps OR spring)
text
wt Format de réponse wt=xml Json
Equation de recherche Termes + opérateurs booléens avec des parenthèses Journal AND (Histoire OR History)
Intervalles Recherche d'intervalles submittedDateY_i:[2000 TO *]
Opérateur booléens AND OR NOT + - && || AND
fq Filtres fq=submitType_s:file
rows Nombre de résultats rows=5 30
start Décalage des résultats start=10 0
fl Champs à retourner fl=auth*,docid,label_s docid,label_s
sort Tri : nom du champ + asc ou desc sort=submittedDateY_i desc score
facet Construire des facettes facet=true false
facet.field Un champ pour faire des facettes facet.field=docType_s
facet.mincount Nombre minimum de valeurs pour retourner une facette facet.mincount=1 0
facet.sort Tri des facettes [count ou index] facet.sort=index count
Valeurs et paramètres sensibles à la casse
42. Types de métadonnées accessibles
Type Usage prévu Exemple
Indexées Recherche title_t
Stockées Affichage label_s
Facettes Liste de valeurs submitType_s
Tri Tri de valeurs
multivaluées
author_sort
• Liste des champs
https://api.archives-ouvertes.fr/docs/search/schema/fields/#fields
43. Paramètre : Format de réponse
• wt=format
• Valeurs : xml ou json
• Exemple :
https://api.archives-ouvertes.fr/search/?wt=xml
44. Paramètre : Critère de recherche
• q=valeur
• Exemple :
https://api.archives-ouvertes.fr/search/?q=dimuons
45. Paramètre : Recherche dans un champ
• q=champ:valeur
• Exemple :
https://api.archives-ouvertes.fr/search/?q=title_t:dimuons
46. Paramètre : Recherche sur plusieurs champs
• q=champ1:valeur1 OPERATEUR champ2:valeur2
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=title_t:dimuons AND
authLastName_t:capelli
47. Paramètre : Filtrer avec un champ
• fq=champ:valeur
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file
48. Paramètre : Champs retournés
• fl=champ1,champ2,…
• Par défault : docid, uri_s, label_s
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file&fl=halId_s,ti
tle_s
49. Paramètre : Groupe
• group=true&group.field=[champ]&group.limit=[limi
t]
• Permet de grouper les résultats en fonction d’un
champ. Permet également de ne retourner qu’un
certain nombre de résultats par groupe
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file&group=true
&group.field=docType_s&group.limit=1
50. Paramètre : Tri
• sort=champ1 (ASC|DESC),champ2 (ASC|DESC),…
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=title_t:dimuons&fq=submitType_s:file&sort=submi
ttedDate_tdate desc
51. Parametre : Pagination
• start=[num 1er resultat]&rows=[nb résultats]
• Convient pour paginer un résultat de recherche
• cursorMark=Id
• Permet de récupérer l’intégralité d’une collection /
de HAL…
• https://api.archives-
ouvertes.fr/search/?q=*:*&wt=xml&rows=100&sor
t=docid%20asc&cursorMark=*&start=0
68. Référentiel des revues
• Lister les revues avec le statut « green » dans
Sherpa/Romeo où l’éditeur est Elsevier et la revue
est validée dans le référentiel
69. Référentiel des revues
• Lister les revues avec le statut « green » dans
Sherpa/Romeo où l’éditeur est Elsevier et la revue
est validée dans le référentiel
• https://api.archives-
ouvertes.fr/ref/journal/?wt=json&q=publisher_t:(El
sevier)&fq=valid_s:VALID&fq=sherpaColor_s:green
&fl=*&sort=title_s asc
73. Documents HAL
• Obtenir la liste d'auteurs affiliés à la
structure AgroParisTech avec le nombre de dépôts
par auteur
• https://api.archives-
ouvertes.fr/search/?q=*%3A*&rows=0&&facet=tru
e&facet.field=structHasAuthId_fs&facet.prefix=148
117_FacetSep_&facet.limit=3000
• Champ structHasAuthId_fs contient :
Identifiant de structure + _FacetSep_ + Nom
structure + _JoinSep_ + Identifiant Auteur +
_FacetSep_ + Nom auteur
87. Etape 3
• Créer une page d’accueil regroupant :
• Liste des derniers dépôts
• Nuage de mot-clés (utilisation wordcloud2.js)
• Graphes représentant les facettes types de documents,
répartition par pays et type de soumission (utilisation
Google Charts)
89. Simple Web-service Offering Repository Deposit
• Basé sur Atom Publishing Protocol (APP)
• Utilisé par d’autres AO & logiciels
• arXiv, Dspace, Eprints, …
• API REST HTTP
• Verbes HTTP :
• GET : statut d’une ressource
• POST : nouveau dépôt
• PUT : modification des métadonnées / nouvelle version
• DELETE : suppression d’une ressource
http://swordapp.org/
90. Entêtes HTTP (1)
• Content-Type :
• text/xml pour le dépôt d’un fichier XML
• application/zip pour le dépôt d’une archive ZIP contenant un
fichier XML + les fichiers associés
• Content-Disposition :
• attachment; filename=tei.xml à utiliser pour indiquer le nom
du fichier XML dans le ZIP
• Packaging :
• http://purl.org/net/sword-types/AOfr : format AOfr - TEI HAL
• http://jats.nlm.nih.gov/publishing/tag-library/ : format JATS
• Content-MD5 :
• Signature MD5 : vérifie l’intégrité du contenu envoyé
91. Entêtes HTTP (2)
• On-Behalf-Of : Dépôt pour le compte d’un utilisateur HAL
• UID ou LOGIN du compte HAL
• IDHAL ou ORCID (prochainement)
• Export-To-Arxiv
• true / false : indique si le dépôt doit être transféré sur ArXiv
• Export-To-PMC
• true / false : indique si le dépôt doit être transféré sur Pubmed Central
• Hide-For-RePEc
• true / false : permet de cacher le dépôt du réservoir accessible à RePEc dans
l'archive HAL
• Hide-In-OAI
• true / false : permet de cacher le dépôt du réservoir OAI-PMH et du Sitemap
• X-Allow-Completion :
• idext : récupération des métadonnées à partir d'un identifiant externe DOI,
arXivID, …
• grobid : récupération des métadonnées à partir du PDF soumis via
l'outil GROBID
• affiliation : recherche des affiliations des auteurs en se basant sur le référentiel
AURéHAL
92. Statut d’une ressource
• GET api.archives-ouvertes.fr/sword/[identifiant]
• Réponse
• HTTP/1.1 200 OK
• statut : accept | verify | update | delete
curl –X GET -u login:pwd https://api.archives-ouvertes.fr/sword/hal-
00000001v2
<?xml version="1.0" encoding="utf-8"?>
<document id="hal-00000001" version="2">
<status>accept</status>
<comment></comment>
</document>
93. Suppression d’une ressource
• DELETE api.archives-ouvertes.fr/sword/[identifiant]
• Réponse
• Suppression OK : HTTP/1.1 204 No Content
• Suppression NOK : Code Erreur
curl –X DELETE -u login:pwd https://api.archives-ouvertes.fr/sword/hal-
01039627
94. Dépôt d’une ressource (1)
• POST api.archives-ouvertes.fr/sword/[portail]
• Liste des portails accessible via l’API : https://api.archives-
ouvertes.fr/ref/instance
• Format pivot basé sur la TEI
• https://hal.archives-ouvertes.fr/documents/aofr.xsd
• Dépôt d’un fichier XML (Content-Type:text/xml)
àNotice ou Texte intégral non intégré au dépôt
• Dépôt d’une archive ZIP (Content-Type:application/zip)
à Texte intégral : fichier(s) intégré(s) au dépôt
95. Dépôt d’une ressource (2)
• Réponse
• Dépôt accepté (passage diret en ligne) :
HTTP/1.1 202 Accepted
• Dépôt créé (en modération dans HAL) :
HTTP/1.1 201 Created
• Problème lors du dépôt :
Code Erreur
curl -X POST -u login:pwd https://api.archives-ouvertes.fr/sword/hal -H "X-
Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml" -
-data-binary @tei.xml
96. Dépôt d’une ressource (3)
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:sword="http://purl.org/net/sword/terms/"
xmlns:dcterms="http://purl.org/dc/terms/" xmlns:hal="http://hal.archives-ouvertes.fr/">
<title>Accepted media deposit to HAL</title>
<id>hal-01040864</id>
<hal:password>9322one</hal:password>
<hal:version>1</hal:version>
<updated>2017-03-28T08:56:23+02:00</updated>
<summary>A media deposit was stored in the HAL workspace</summary>
<sword:treatment>stored in HAL workspace</sword:treatment>
<sword:userAgent>HAL SWORD API Server</sword:userAgent>
<source>
<generator uri="https://api.archives-ouvertes.fr/sword"
version="1.0">hal@ccsd.cnrs.fr</generator>
</source>
<link rel="alternate" href="https://hal.archives-ouvertes.fr/hal-01040864"/>
</entry>
97. Modification des métadonnées
• PUT api.archives-ouvertes.fr/sword/[identifiant]
• Réponse
• Modification OK : HTTP/1.1 200 OK
• Modification NOK : Code Erreur
curl -X PUT -u login:pwd https://api.archives-ouvertes.fr/sword/hal-
01040864 -H "X-Packaging:http://purl.org/net/sword-types/AOfr" -H
"Content-Type:text/xml" --data-binary @new_tei.xml
98. Dépôt d’une nouvelle version
• Idem modification des métadonnées + ajout du
texte intégral
• PUT api.archives-ouvertes.fr/sword/[identifiant]
• Réponse
• Dépôt OK : HTTP/1.1 201 Created
• Dépôt NOK : Code Erreur
curl -X PUT -u login:pwd https://api.archives-ouvertes.fr/sword/hal-
01040864 -H "X-Packaging:http://purl.org/net/sword-types/AOfr" -H
"Content-Type:text/xml" --data-binary @new_tei.xml
99. Gestion des erreurs (1)
• HTTP/1.1 4XX
• 406 Not Acceptable
• Packaging non reconnu
• Content-type non reconnu
• Erreur dans chargement du fichier XML
• 412 Precondition Failed
• Problème dans la vérification du MD5
• 403 Forbidden
• Problème d’authentification
• 405 Method Not Allowed
• Utilisation d’un verbe HTTP non accepté
• 413 Request Entity Too Large
• Taille du fichier supérieur à la limite (200Mo)
• 400 Bad Request
• Erreur d’enregistrement
100. Gestion des erreurs (2)
• Xpath : /sword:error/sword:verboseDescription
<?xml version="1.0" encoding="utf-8"?>
<sword:error xmlns:sword="http://purl.org/net/sword/error/" xmlns="http://www.w3.org/2005/Atom"
href="http://purl.org/net/sword/error/ErrorBadRequest">
<title>ERROR</title>
<updated>2017-03-28T10:13:50+02:00</updated>
<author>
<name>HAL SWORD API Server</name>
</author>
<source>
<generator uri="https://api.archives-ouvertes.fr/sword"
version="1.0">hal@ccsd.cnrs.fr</generator>
</source>
<summary>Some parameters sent with the request were not understood</summary>
<sword:treatment>processing failed</sword:treatment>
<sword:verboseDescription>{"meta":{"abstract":{"isEmpty":"Vous devez remplir ce
champ"}}}</sword:verboseDescription>
<link rel="alternate" href="https://api.archives-ouvertes.fr" type="text/html"/>
</sword:error>