qui est le plus clair et en anglais.
remarquer les 5 formats de l'export
Intro
Les APIs (Application Programming Interface) sont des interfaces qui permettent une communication machine à machine. Cette page vous donne accès à la documentation des APIs de HAL v3.0:https://api.archives-ouvertes.fr/docs
Il y a 3 API
- SWORD import
Effectuer un dépôt sur HAL grâce à l'API SWORD. - HAL OAI-PMH server.
- Search HAL resources via an API.
On va se focaliser sur la première API SWORD.
import
les ressources internes
GitHub HAL
HAL
HAL is an open archive where authors can deposit scholarly documents from all academic fields
JavaScript Updated on 10 Nov 2016 (@janv 2017)
Episciences.org
The main idea of the Episciences.org project is to provide a technical platform of peer-reviewing
Updated on 21 Apr 2015 (@janv 2017)
Sciencesconf.org
Sciencesconf.org is a Web platform available to all organizers of scientific conferences.
Updated on 12 Mar 2015 (@janv 2017)
API de dépôt SWORD
une documentation des processus SWORD sur HAL.
intro
L'API de dépôt SWORD permet l'import automatique de documents dans l'archive ouverte HAL (hal.archives-ouvertes.fr).
nous avons choisi le protocole SWORD (Simple Web-service Offering Repository Deposit), standard d’échanges international fondé par le JISC (Joint Information Systems Committee) pour les imports.
http://swordapp.org/about/
https://www.jisc.ac.uk/about
Le protocole SWORD définit un ensemble de services Web basé sur Atom Publishing Protocol (APP), RFC5023.
https://www.ccsd.cnrs.fr/fr/2013/11/les-api-dans-hal-v3/
http://swordapp.org/
https://www.ccsd.cnrs.fr/fr/2013/11/les-api-dans-hal-v3/
http://swordapp.org/
La version implémentée dans HAL de SWORD/APP suit de près la version 2.0 du protocole.
SWORD version 2 is a new initiative to update the SWORD v1 standard in order to allow it to cope not only with the traditional ‘fire and forget’ deposit scenario, but also to facilitate the functions needed to support the whole deposit lifecycle of scholarly works.
The Atom Publishing Protocol (AtomPub) is an application-level protocol for publishing and editing Web resources. The protocol is based on HTTP transfer of Atom-formatted representations. The Atom format is documented in the Atom Syndication Format.
https://tools.ietf.org/html/rfc5023
The Internet Engineering Task Force (IETF®)
https://www.ietf.org/
SWORD version 2 is a new initiative to update the SWORD v1 standard in order to allow it to cope not only with the traditional ‘fire and forget’ deposit scenario, but also to facilitate the functions needed to support the whole deposit lifecycle of scholarly works.
The Atom Publishing Protocol (AtomPub) is an application-level protocol for publishing and editing Web resources. The protocol is based on HTTP transfer of Atom-formatted representations. The Atom format is documented in the Atom Syndication Format.
https://tools.ietf.org/html/rfc5023
The Internet Engineering Task Force (IETF®)
https://www.ietf.org/
Using SWORD
Depositing is a two-stage process within APP and SWORD. First, a request from an authenticated user is sent to the implementation for what APP calls the ‘service document’, this returns details of the collections that user is allowed to deposit to within the repository. At this point, the user may deposit their file into the chosen collection. Various things may prevent success, for example lack of authentication credentials, unacceptable file format or a corrupt MD5 checksum. The repository will send a respond indicating the success, or otherwise of the deposit.Avant d'utiliser SWORD sur HAL
Le dépôt via le protocols SWORD nécessite l'utilisation d'un compte déposant valide.L'authentification s'effectue grâce à la méthode HTTP Basic.
L'API SWORD de HAL permet de spécifier dans l'entête HTTP On-Behalf-Of le(les) identifiant(s)/uid du(des) compte(s) pour le(s)quel(s) l'action est effectuée. Le caractère ";" sert de séparateur.
Les métadonnées transmises via ce protocole sont celles généralement utilisées dans HAL. Il est donc nécessaire d'être familier avec un dépôt dans HAL. En particulier, chaque dépôt devra être catégorisé suivant les disciplines scientifiques de HAL et rangé suivant un des types de document, etc. L'accès aux référentiels utilisés dans HAL est disponible ici.
https://api.archives-ouvertes.fr/docs/ref/
Voir ci-dessous structure "des types de document" : Fields of reference
En cas d'erreurs, d'entêtes non compréhensibles ou de contenus incorrects l'API utilise les erreurs SWORD standards introduites dans le paragraphe "La gestion des erreurs" ci-dessous.
Effectuer un dépôt
Le point d'entrée (BaseURL) de l'API SWORD sur HAL esthttps://api.archives-ouvertes.fr/sword
Une version de test est disponible :
https://api-preprod.archives-ouvertes.fr/sword
pour tester vos développements dans un environnement HAL très proche de la production.
L'objet servicedocument
Ce service permet de connaitre les caractéristiques de l'API SWORD sur HAL. Il permet en particulier de récupérer les formats XML connus pour l'import des notices.L'URL de ce service est
https://api.archives-ouvertes.fr/sword/servicedocument
Chaque portail de HAL est défini comme une collection au sens SWORD. L'URL de dépôt pour le portail Hal est ainsi définie : https://api.archives-ouvertes.fr/sword/hal
Le format de métadonnées
Le format de métadonnées à utiliser pour l'import SWORD dans HAL est basé sur le format TEI.http://www.tei-c.org/index.xml
L'URL, dans l'entête HTTP Packaging du protocole HTTP, est
http://purl.org/net/sword-types/AOfr
Le schéma XML est disponible sur https://api.archives-ouvertes.fr/documents/aofr-sword.xsd.
L'ensemble des métadonnées possibles sont à retrouver ici : Le format XML complet avec documentation intégrée
https://api.archives-ouvertes.fr/documents/all.xml
Voir à la fin de ce post pour plus de détails.
Les exemples
Vous pouvez tester les exemples suivants :- Article dans une revue : télécharger le xml
https://api.archives-ouvertes.fr/documents/art.xml - Communication avec document : télécharger le zip
https://api.archives-ouvertes.fr/documents/depot.zip
Des exemples par type de document sont également disponibles sur le : dépôt Github du CCSD
https://github.com/CCSDForge/HAL/tree/master/Sword
Le dépôt
Le dépôt via cette API consiste au transfert (requête HTTP POST)- soit d'un fichier XML
- soit d'une archive ZIP contenant la fiche descriptive, au format XML, de la ressource plus une(des) pièce(s) jointe(s) correspondant au texte intérgal et pointée(s) dans le fichier XML.
Le format XML est annoncé au serveur via l'entête HTTP Packaging. Il faut renseigner l'entête Content-Type pour indiquer au serveur le type de contenu (application/zip ou text/xml). Dans le cas d'une archive ZIP, le nom du fichier XML est indiqué dans l'entête HTTP Content-Disposition. Il est possible de s'assurer de l'intégrité du contenu envoyé en fournissant sa signature md5 dans l'entête HTTP Content-MD5.
HAL propose 4 entêtes HTTP spécifiques pour le dépôt :
- Export-To-Arxiv : indique si le dépôt doit être transféré sur l'archive arXiv [true ou false, défaut : false]
- Export-To-PMC : indique si le dépôt doit être transféré sur l'archive PubMed Central [true ou false, défaut : false]
- Hide-For-RePEc : permet de cacher le dépôt du reservoire accessible à RePEc dans l'archive HAL [true ou false, défaut : false]
- Hide-In-OAI : permet de cacher le dépôt du reservoire OAI-PMH et du Sitemap [true ou false, défaut : false]
https://en.wikipedia.org/wiki/PubMed_Central
https://fr.wikipedia.org/wiki/ArXiv
Dans le cas d'un dépôt de notice sans document (la référence à un fichier target="DOC.pdf" doit être supprimée) la réponse en cas de succès est "202 Accepted".
Un formulaire Web permettant de déposer votre fichier XML ou ZIP est disponible sur https://api.archives-ouvertes.fr/sword/upload/
La mise à jour
Mise à jour d'un document
Lorsqu'un dépôt est accepté sur l'archive HAL, il est possible de remplacer son contenu en déposant une nouvelle version. Via l'API SWORD il faut utiliser la requête HTTP PUT sur l'URL https://api.archives-ouvertes.fr/sword/%identifiant ressource% en incluant dans le contenu HTTP soit un fichier ZIP (fichier + XML) soit un fichier XML dans le format annoncé dans l'entête Packaging. Il faut renseigner l'entête Content-Type pour indiquer au serveur le type de c ntenu. Dans le cas d'une archive ZIP, le nom du fichier XML est indiqué dans l'entête HTTP Content-Disposition. Il est possible de s'assurer de l'intégrité du contenu envoyé en fournissant sa signature md5 dans l'entête HTTP Content MD5.Exemple : PUT https://api.archives-ouvertes.fr/sword/hal-00000002 HTTP/1.1 Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Type: application/zip Packaging: http://purl.org/net/sword-types/AOfr Content-Disposition: attachment; filename=meta.xml ZIP file content ...En cas de succès, la réponse du serveur est "201 Created" et un contenu décrivant une entrée SWORD.
Dans le cas d'un dépôt de notice, sans document, la réponse en cas de succès est "202 Accepted".
curl -v -u test_ws:test https://api-preprod.archives-ouvertes.fr/sword/hal-00000010 -H "Packaging:http://purl.org/net/sword-types/AOfr" -X PUT -H "Content-Type:application/zip" -H "Content-Disposition: attachment; filename=comm.xml" --data-binary @depot.zip
Mise à jour des métadonnées
Lorsqu'un dépôt est accepté sur l'archive HAL, il est possible de corriger/modifier les métadonnées descriptives du dépôt. Via l'API SWORD il faut utiliser la requête HTTP PUT sur l'URL https://api.archives-ouvertes.fr/sword/identifiant ressourcevversion en incluant dans le contenu HTTP le XML dans le format annoncé dans l'entête Packaging. Il est possible de s'assurer de l'intégrité du contenu envoyé en fournissant sa signature md5 dans l'entête HTTP Content-MD5.Exemple : PUT https://api.archives-ouvertes.fr/sword/hal-00000002v3 HTTP/1.1 Authorization: Basic ZGFmZnk6c2VjZXJldA== On-Behalf-Of: test Content-Type: text/xml Packaging: http://purl.org/net/sword-types/AOfr <?xml version="1.0"?> <TEI> ...
En cas de succès, la réponse du serveur est "200 OK" et un contenu décrivant une entrée SWORD.
curl -X PUT -d @comm.xml -v -u test_ws:test https://api-preprod.archives-ouvertes.fr/sword/hal-00000050 -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml"
La suppression
Il est possible de supprimer des ressources de HAL via l'API SWORD pour des dépôts de notices, sans document, ou des dépôts non encore acceptés en effectuant la requête HTTP DELETE sur l'URL https://api.archives-ouvertes.fr/sword/%identifiant ressource%v%version%Exemple : DELETE https://api.archives-ouvertes.fr/sword/hal-00000002 HTTP/1.1 Authorization: Basic ZGFmZnk6c2VjZXJldA==En cas de succès, la réponse du serveur est "204 No Content".
curl -X DELETE -v -u test_ws:test https://api-preprod.archives-ouvertes.fr/sword/hal-00000010
Le statut d'un dépôt
Une requête HTTP GET sur l'URL https://api.archives-ouvertes.fr/sword/%identifiant ressource%v%version% permet de connaitre le statut d'une ressource.Le statut retourné est :
- accept : la ressource est en ligne
- replace : la ressource a une nouvelle version
- verify : le dépôt est en validation
- update : une(des) modification(s) a(ont) été demandée(s) lors de la validation
- delete : la ressource a été refusée
Le champ comment permet de connaître la(les) raison(s) du refus ou de la modification.
Si la personne connectée est le déposant ou un des propriétaires du dépôt, le mot de passe du dépôt est également retourné (attribut password de document)
Exemple : GET https://api.archives-ouvertes.fr/sword/hal-00000001v1
Schéma de retour :
<document id="hal-00000001" version="1">
<status>accept|replace|verify|update|delete</status>
<comment></comment>
</document>
curl -X GET -v -u test_ws:test https://api-preprod.archives-ouvertes.fr/sword/hal-0000002
La gestion des erreurs
La gestion des erreurs est décrite dans la partie 12 de la spécification SWORD, où un élément appelé sword:error est introduit.http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html#errordocuments
Ce message permet d'apporter plus d'informations aux ordinaires 4xx et/ou 5xx du protocole HTTP.
Le contenu de la réponse d'erreur est un noeud Atom classique dont l'élément racine est sword:error, un attribut href contenant une URI qui identifie l'erreur, un champ title présentant un code erreur et une erreur humaine présenté dans l'élément summary et/ou sword:verboseDescription.
Le statut HTTP pour toutes les erreurs qui ne sont pas définies dans les spécifications SWORD est "400 Bad Request".
La réponse SWORD
En cas de succès des verbes POST (dépôt) ou PUT (modification ou nouvelle version) le serveur retourne un document XML : Atom Entry Document.http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html#depositreceipt
L'identifiant, le mot de passe et la version de la ressource déposée sont disponible dans ce retour.
Exemple complet de retour :
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:hal="http://hal.archives-ouvertes.fr/">
<title>Accepted media deposit to HAL</title>
<id>hal-00000001</id>
<hal:password>XXXXXXXX</hal:password>
<hal:version>1</hal:version>
<updated>2015-03-27T15:04:31+01: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-00000001"/>
</entry>
How to make an XML import ?
see the .docx below.
just this intro:
- Before using this service, you must already have an account on HAL or create a new one.
- Create your XML files with an XML editor. Consult the section “1.2. Help for the XML file construction”. Beware : you have to create one XML file for each publication.
- You have the possibility to make 2 different types of uploads: uploads without any attached file(s) (notice) or a deposit with an attached file(s). Consult the section “1.3.2. General elements : <editionStmt>”
- Validate your XML file with the XML schema of HAL on an XML editor or by command-line on Linux by copying the XML schema of HAL on your disk and launching the following command-line:
xmllint --noout TEI_COUV_complet_Sword.xml --schema aofr-sword.xsd - If you want, you can import your files via a Web-API.
- Connexion with your HAL login and password.
- Import your articles by transferring your XML files one by one.
- After your submission, there is a validation step .
- After the validation and if no modification is required, your document is online.
Guideline Fichier doc
https://github.com/CCSDForge/HAL/blob/master/Sword/SWORD_import_HAL.docStructure du fichier TEI XML HAL
TEI pour import/export HALFormat standard choisit pour l’import/export dans HAL
Décomposition et explication du fichier TEI de HA:
http://aramis.resinfo.org/wiki/lib/exe/fetch.php?media=ateliers:aramis-hal-v3-le-format-tei_25_02_2015.pdf
conversion entre de nombreux formats
http://www.tei-c.org/oxgarage/#OxGarage is an web, and RESTful, service to manage the transformation of documents between a variety of formats. The majority of transformations use the Text Encoding Initiative format as a pivot format
https://github.com/TEIC/Oxgarage
The TEI Special Interest Group on Scholarly Publishing, approved and created in June 2009, focuses on the use of TEI in original scholarly publication, as the medium of authorship and archival format from which print, Web, ebook, and other formats may be derived.
http://www.tei-c.org/Activities/SIG/Publishing/index.xml
Outils pour les formats TEI
The Text Encoding Initiative (TEI) is a consortium which collectively develops and maintains a standard for the representation of texts in digital form. Its chief deliverable is a set of Guidelines which specify encoding methods for machine-readable texts, chiefly in the humanities, social sciences and linguistics. Since 1994, the TEI Guidelines have been widely used by libraries, museums, publishers, and individual scholars to present texts for online research, teaching, and preservation.http://www.tei-c.org/index.xml
example:
http://www.tei-c.org/Activities/Projects/ta01.xml
and see the structure xml:
http://www.tei-c.org/Activities/Projects/ta01.xml?style=raw
