Le document présente les API de l'archive ouverte HAL, destinée à l'archivage et la diffusion des publications scientifiques. Il décrit les différents types d'API, leur utilisation, ainsi que les techniques d'accès et de dépôt des documents. Des exemples concrets illustrent les requêtes API et les types de métadonnées disponibles pour les contributeurs et chercheurs.

1. JDEV 2017 – Atelier T5.A02
Usage des API de HAL
Yannick Barborini - CCSD

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

4. Introduction

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

8. Pré-requis technique
• Pas d’authentification
• Client HTTP
• Navigateur web
• cURL
• Bibliothèque logicielle
• …

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

10. Infrastructure
Indexation
Réplication
Dépôt dans HAL
API
Mise en
ligne
master
slaves

11. Accès aux référentiels
https://api.archives-ouvertes.fr/docs/ref

12. Recherche
• Tous les modèles de données sont accessibles
via l’API
• https://api.archives-ouvertes.fr/ref/referentiel
• Format de réponse SOLR (type)
• <reponse>
• <result …>
• Les formats de sortie json ou xml

13. Liste des référentiels
Référentiel Description URL
anrproject Projets ANR /ref/anrproject
author Auteurs /ref/author
authorstructure Affiliation des auteurs /ref/authorstructure
doctype * Types de documents /ref/doctype
domain Disciplines scientifiques /ref/domain
europeanproject Projets européens /ref/europeanproject
instance * Portail HAL /ref/instance
journal Revues /ref/journal
metadata * Métadonnées /ref/metadata
metadatalist * Métadonnées – listes fermées /ref/metadatalist
structure Structures de recherche /ref/structure
* Référentiels utilisés principalement pour le dépôt

14. Les référentiels pour le dépôt SWORD

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

16. Les portails
• Obtenir la liste des portails disponibles de HAL :
https://api.archives-ouvertes.fr/ref/instance
wt=json wt=xml

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

19. Listes fermées
• Permet d’avoir les valeurs possibles pour les listes
fermées
• Exemple :
• Niveau du cours :
https://api.archives-ouvertes.fr/ref/metadatalist?q=metaName_s:lectureType

20. Les référentiels AURéHAL

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

22. Auteurs
• Accès aux formes auteurs associées aux
publications présentes dans HAL
• Une forme auteur est définie par
• Nom, Prénom, autre prénom, adresse mail
• Aligné avec des référentiels externes (IDHAL,
ORCID, IdRef, …)
• Documentation :
https://api.archives-ouvertes.fr/docs/ref/resource/author
• Liste des champs :
https://api.archives-
ouvertes.fr/docs/ref/resource/author/schema/fields/#fields

23. Auteurs - exemple
• https://api.archives-ouvertes.fr/ref/author?q=docid:49567&fl=*

24. Structures
• Représentation d’une structure dans AuréHAL
• 4 niveaux
Institution
Laboratoire
Département
Equipe
Equipe
Laboratoire
Département
Laboratoire

25. Structures
• Représentation d’une structure dans AuréHAL
• 6 niveaux (09/17)
Regroupement
Institutions
Institution
Regroupement
Laboratoires
Laboratoire
Département
Equipe
Equipe
Laboratoire
Département
Laboratoire

26. Structure - Exemple
• Structure ADAC
ADAC
LIRMM
CNRS
UMONTPELLIER

27. Structures - Exemple
• Exemple avec la structure ADAC
https://aurehal.archives-ouvertes.fr/structure/read/id/487991

28. Structures - Exemple
https://api.archives-ouvertes.fr/ref/structure?q=docid:487991&fl=*

29. Structures – liste des champs
• https://api.archives-ouvertes.fr/docs/ref/resource/structure/schema/fields/#fields

30. Disciplines scientifiques
• Origine disciplines arXiv + département SHS du CNRS
• Documentation
https://api.archives-ouvertes.fr/docs/ref/resource/domain
• Exemple
https://api.archives-ouvertes.fr/ref/domain?q=code_s:phys&fl=*

31. Revues
• Lien avec sherpa/Roméo pour la politique des
éditeurs
www.sherpa.ac.uk/romeo
• Documentation
api.archives-ouvertes.fr/docs/ref/resource/journal
Exemple
api.archives-ouvertes.fr/ref/journal?q=nature&fl=*

32. Projets ANR
• Récupération à partir de l’ANR
• Documentation
api.archives-ouvertes.fr/docs/ref/resource/anrproject
• Exemple
api.archives-ouvertes.fr/ref/anrproject?q=*&fl=*

33. Projets européens
• Moissonnage d’OpenAIRE
• Documentation
https://api.archives-ouvertes.fr/docs/ref/resource/europeanproject
• Exemple
https://api.archives-ouvertes.fr/ref/europeanproject?q=*&fl=*

34. L’API de recherche d’affiliations

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)

36. Accès aux documents
https://api.archives-ouvertes.fr/docs/search

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é

38. Point d’entrée
• Point d’entrée pour les documents de HAL:
http://api.archives-ouvertes.fr/search/hal

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

52. Le système de facettes

53. Les facettes
Groupement de résultats
de recherche dans des
catégories avec le nombre
de documents
correspondant à chaque
catégorie

54. Les facettes
• Créer des regroupements
facet=true&facet.field=champ1
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=*:*&rows=0&facet=true&f
acet.field=docType_s

55. Les pivots
• Créer des regroupements à
plusieurs dimensions
• facet=true&facet.pivot=champ1,
champ2
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=*&rows=0&facet=true&fa
cet.pivot=docType_s,submitType_s

56. Les ranges
• Créer des regroupements
(principalement utilisé pour les
dates)
• facet=true&facet.range=champ
• Exemple :
https://api.archives-
ouvertes.fr/search/?q=*:*&rows=0&indent=true
&facet=true&facet.range=submittedDateY_i&fac
et.range.start=1990&facet.range.end=2010&fac
et.range.gap=2

57. Ateliers

58. Requêtes

59. Référentiel Auteur
• Rechercher les auteurs qui ont Inria comme
établissement d’appartenance. Retourner tous les
champs se terminant par Name_s triés par nom de
famille

60. Référentiel Auteur
• Rechercher les auteurs qui ont Inria comme
établissement d’appartenance. Retourner tous les
champs se terminant par Name_s triés par nom de
famille
https://api.archives-
ouvertes.fr/ref/author/?q=structureId_i:300009&wt=json&sort=lastName_s
%20asc%20&fl=*Name_s

61. Référentiel Auteur
• Lister les auteurs qui ont Inria comme établissement
d’appartenance et qui ont un idHAL. Retourner le
nom de l’auteur ainsi que son idHAL et son ORCID

62. Référentiel Auteur
• Lister les auteurs qui ont Inria comme établissement
d’appartenance et qui ont un idHAL. Retourner le
nom de l’auteur ainsi que son idHAL et son ORCID
https://api.archives-
ouvertes.fr/ref/author/?q=structureId_i:300009&fq=idHal_s:["" TO *]
&fl=fullName_s,idHal_s,orcid_s
Idem mais retourner les auteurs qui n’ont pas d’idHAL

63. Référentiel Structures
• Lister les laboratoires rattachés à Inria qui ont un
identifiant RNSR. Retourner le nom du laboratoire
ainsi que l’identifiant RNSR

64. Référentiel Structures
• Lister les laboratoires rattachés à Inria qui ont un
identifiant RNSR. Retourner le nom du laboratoire
ainsi que l’identifiant RNSR
• https://api.archives-
ouvertes.fr/ref/structure/?q=*&fq=parentDocid_i:3
00009&fq=type_s:laboratory&fq=rnsr_s:["" TO
*]&fl=acronym_s,name_s,rnsr_s

65. Référentiel Structures
• Idem en les groupant par type de structure

66. Référentiel Structures
• Idem en les groupant par type de structure
https://api.archives-
ouvertes.fr/ref/structure/?q=*&fq=parentDocid_i:300
009&fq=rnsr_s:["" TO *]&fl=acronym_s,name_s,rnsr_s
&group=true&group.field=type_s&group.limit=100

67. Référentiel Structures
• Retourner la liste des types de structures (avec le
nombre d’occurrences) associés au CNRS
https://api.archives-
ouvertes.fr/ref/structure/?q=*:*&fq=parentDocid_i:
441569&rows=0&facet=true&facet.field=type_s&fac
et.mincount=1

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

70. Documents HAL
• Lister les articles de la collection LKB déposés en
2006 et qui ont un texte associé

71. Documents HAL
• Lister les articles de la collection LKB déposés en
2006 et qui ont un texte associé
https://api.archives-
ouvertes.fr/search/LKB?q=*&fq=submittedDateY_i:2
006&fq=submitType_s:file&fq=docType_s:ART

72. Documents HAL
• Obtenir la liste d'auteurs affiliés à la
structure AgroParisTech avec le nombre de dépôts
par auteur

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

74. Documents HAL

75. Documents HAL
• Retourner le nombre de dépôts par année, type de
dépôt et type de document

76. Documents HAL
• Retourner le nombre de dépôts par année, type de
dépôt et type de document
https://api.archives-
ouvertes.fr/search/?q=*:*&rows=0&facet=true&face
t.pivot=submittedDateY_i,submitType_s,docType_s

77. Documents HAL
• Retourner le documents présents dans la collection
LKB mais pas dans la collection UPMC

78. Documents HAL
• Retourner le documents présents dans la collection
LKB mais pas dans la collection UPMC
https://api.archives-
ouvertes.fr/search/LKB/?q=*:*&wt=xml&fq=collCode
_s:(NOT UPMC)

79. Documents HAL
• Récupérer les liens vers toutes les vidéos dans
médiHAL

80. Documents HAL
• Récupérer les liens vers toutes les vidéos dans
médiHAL

81. Documents HAL
• Récupérer les liens vers toutes les vidéos dans
médiHAL
https://api.archives-
ouvertes.fr/search/medihal?q=*&fq=docType_s:VIDE
O&fl=files_s

82. Création d’une interface de recherche basée sur les API

83. Atelier
• Construire une petite application Web
d’interrogation de l’archive HAL basée sur les API
• Récupération du projet
• https://github.com/ybarborini/jdev-t5A02
• Récupérer la branche « master »
• Lancer bower install pour récupérer les librairies Js
utilisées dans le projet

84. Atelier
• Construire une petite application Web
d’interrogation de l’archive HAL basée sur les API
• Récupération du projet
• https://github.com/ybarborini/jdev-t5A02
• Récupérer la branche « master »
• Lancer bower install pour récupérer les librairies Js
utilisées dans le projet
• Si pb avec bower : récupérer le répertoire libraries à
l’adresse :
https://hal.archives-ouvertes.fr/public/jdev/libraries.zip

85. Etape 1
• Récupération des métadonnées d’un document
• Mise en page de ce document
• Ex http://localhost/jdev-t5A02/?halid=hal-
00000001 récupèrera les métadonnées de l’article
dans HAL et le mettra en page

86. Etape 2
• Créer une page avec un champ de recherche
• Effectuer une recherche avec l’API et retourner les
résultats de recherche / facette (type de dépôt,
discipline primaire, auteur)
• Effectuer la mise en page

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)

88. Import SWORD
https://api.archives-ouvertes.fr/docs/sword

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>

101. Liens utiles
Exemples en ligne de requêtes sur l’API de
recherche HAL :
Base de connaissance de HAL :
https://wiki.ccsd.cnrs.fr/wikis/hal/
Documentation API Recherche HAL : https://api.archives-
ouvertes.fr/docs/search
Extension Chromium/Chrome pour visualiser JSON :
- JSONViewer-for-Chrome :
https://github.com/teocci/JSONViewer-for-Chrome
Extension Firefox pour visualiser JSON :
- JSON-formatter
https://addons.mozilla.org/fr/firefox/addon/json-
formatter