Import SWORD

  1. Documentation
  2. Import SWORD (dernière mise à jour le 24/03/2017)
  1. Introduction
  2. Avant d'utiliser SWORD sur HAL
  3. Effectuer un dépôt
  4. La mise à jour
  5. La suppression
  6. Le statut d'un dépôt
  7. La gestion des erreurs
  8. La réponse SWORD
  9. Options de dépôt
  10. Identification des auteurs et des affiliations
  11. Questions / support

1. Introduction

L'API de dépôt SWORD permet l'import automatique de documents dans l'archive ouverte HAL (hal.archives-ouvertes.fr).

Le protocole SWORD définit un ensemble de services Web basé sur Atom Publishing Protocol (APP), RFC5023.

La version implémentée dans HAL de SWORD/APP suit de près la version 2.0 du protocole.

L'idée de ce manuel est de fournir une documentation des processus SWORD sur HAL.

2. 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 grace à la méthode HTTP Basic.

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.

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 7 ci-dessous.

3. 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 environement HAL très proche de la production.

3.1 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

3.2 Déposer pour un autre compte

L'API SWORD de HAL permet de spécifier dans l'entête HTTP On-Behalf-Of le ou les comptes pour lesquels l'action est effectuée.

Syntaxe : 

Type Identifiant|identifiant

Le caractère "|" sert de séparateur entre l'identifiant et sa valeur.

Exemples :

login|marvin
uid|42
idhal|arthur-dent

        ORCID|0000-0002-9079-593X

Si aucun type d'identifiant n'est spécifié, par défaut l'identifiant sera considéré comme un login ou un UID

Le caractère ";" sert de séparateur entre plusieurs identifiants.

Types d'identifiants acceptés :

login ; uid ; idhal ; orcid

Exemple avec plusieurs identifiants :

On-Behalf-Of: marvin;uid|42;idhal|arthur-dent;ORCID|0000-0002-9079-593X

Exemple avec cURL :

curl -X POST -d @meta.xml -v -u login:password https://api.archives-ouvertes.fr/sword/hal/ -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml" -H "On-Behalf-Of: login|marvin;idhal|arthur-dent;ORCID|0000-0002-9079-593X"

3.3 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. L'URI, 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://hal.archives-ouvertes.fr/documents/aofr.xsd.

L'ensemble des métadonnées possibles sont à retrouver ici : Le format XML complet avec documentation intégrée

3.4 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

3.5 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égral 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 5 entêtes HTTP spécifiques pour le dépôt :

3.5.1 Le dépôt de documents

Dans le cas d'un dépôt de fichier, il est indispensable que le fichier de métadonnées, meta.xml pointe vers le document grâce à la mention : target="DOC.pdf". L'archive zip doit donc contenir meta.xml et DOC.pdf. 
        Exemple :

        POST https://api.archives-ouvertes.fr/sword/hal/ HTTP/1.1
        Authorization: Basic ZGFmZnk6c2VjZXJldA==
        On-Behalf-Of: test;identifiant;compte;1
        Content-Type: application/zip
        Packaging: http://purl.org/net/sword-types/AOfr
        Content-MD5: 58e4be161735eb2d3cf32be0c9717b56
        Content-Disposition: attachment; filename=meta.xml

        ZIP file content
        ...

En cas de succès, la réponse du serveur est "201 Created" avec une entête HTTP Location pointant vers la ressource créée et un contenu décrivant une entrée SWORD.

L'identifiant du dépôt créé ainsi que l'URL pérenne sont disponible dans l'entrée XML SWORD retournée aux emplacements suivants : entry/id et entry/link/@href

Exemple avec cURL : 

        curl -v -u login:password https://api.archives-ouvertes.fr/sword/hal/ -H "Packaging:http://purl.org/net/sword-types/AOfr" -X POST -H "Content-Type:application/zip" -H "Content-Disposition: attachment; filename=comm.xml" --data-binary @depot.zip

3.5.2 Le dépôt de notices

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

Exemple avec cURL : 

            curl -X POST -d @meta.xml -v -u login:password https://api.archives-ouvertes.fr/sword/hal/ -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml"

3.6 Client Web

Un formulaire Web permettant de déposer votre fichier XML ou ZIP est disponible sur https://api.archives-ouvertes.fr/sword /upload/

4. La mise à jour

4.1 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 contenu. 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 login:password https://api.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

4.2 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 login:password https://api.archives-ouvertes.fr/sword/hal-00000050 -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml"

5. 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 login:password https://api.archives-ouvertes.fr/sword/hal-00000010

6. 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 :

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 login:password https://api.archives-ouvertes.fr/sword/hal-0000002

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

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

L'identifiant, le mot de passe et la version de la ressource déposée sont disponibles 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>

9 . Options de depot

Au moyen d’entêtes Http spécifiques, il est possible de modifier le comportement du dépôt:
Nouveau Tester le dépôt ou la mise à jour sans effectuer l'opération
X-test: 1
Nouveau Ne pas écraser les affiliations existantes
LoadFilter: noaffiliation
Nouveau Ne pas écraser les domaines existants
LoadFilter: nodomain
Nouveau Contrôler le comportement par rapport aux doublons sur titre.
ForceDoublonByTitle: 0 empêchera de déposer un document dont le titre est déjà présent sur Hal.
ForceDoublonByTitle: 1 ne contrôlera plus les doublons sur titre et par conséquent autorisera le dépôt, meme s'il un article avec le même titre est déjà présent.
Par défaut, la valeur actuelle est 0

Nouveau10 . Identification des auteurs et des affiliations

Pour identifier les auteurs présents dans HAL, il est recommandé de renseigner les identifiants externes de type : idHAL, ORCID, IDref, Arxiv, par exemple :

        
                <author role="crp">
                    <persName>
                        <forename type="first">Forename</forename>
                        <surname>Surname</surname>
                    </persName>
                    <email>nom.prenom@instit.fr</email>
                    <idno type="idhal">forename-surname</idno>
                    <idno type="arXiv">http://arxiv.org/a/forename_r_1</idno>
                    <idno type="IdRef">http://www.idref.fr/060702499</idno>
                    <idno type="ORCID">http://orcid.org/0000-0002-9856-5687</idno>
                    <affiliation ref="#localStruct-1"/>
                </author>

Pour identifier les structures présentes dans HAL, il suffit de renseigner les identifiants externes disponibles pour les structures de type : RNSR, ROR, ISNI, IdRef par exemple :

        
                <back>
                    <listOrg type="structures">
                        <org type="laboratory" xml:id="localStruct-1">
                            <orgName>Mon nouveau laboratoire</orgName>
                            <idno type="RNSR">201422428X</idno>
                            <idno type="ROR">05y76vp24</idno>
                            <idno type="ISNI">201422428X</idno>
                            <desc>
                            <address>
                                <addrLine>adresse du laboratoire</addrLine>
                                <country key="FR"/>
                            </address>
                            </desc>
                        </org>
                        ...
                    </listOrg>
                </back>

Note : selon les changements de tutelles, une structure peut être présente plusieurs fois dans auréHAL avec le même identifiant, dans ce cas la date de publication renseignée dans les métadonnées du dépôt est prise en compte pour déterminer l'entrée adéquate

11. Questions ?

Merci de contacter le support HAL pour toutes questions ou remarques