Saturday, January 14, 2017

API v3 HAL, import to HAL.

voir le fichier "Guideline Fichier doc " à la fin  (iframe .docx)
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/

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/

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 est
  https://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 :

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:

  1. Before using this service, you must already have an account on HAL or create a new one.
  2. 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.
  3. 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>”
  4. 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
  5. If you want, you can import your files via a Web-API.
  6. Connexion with your HAL login and password.
  7. Import your articles by transferring your XML files one by one.
  8. After your submission, there is a validation step .
  9. 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.doc





Structure du fichier TEI XML HAL

TEI pour import/export HAL
Format 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

Tools

http://www.tei-c.org/Tools/




Posted by at
Labels: , , , , , , , ,

3 comments:

Subscribe to: Post Comments (Atom)