Import SWORD

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.

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.

Le point d'entrée (BaseURL) de l'API SWORD sur HAL est https://halspm-api.ccsd.cnrs.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.

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://halspm-api.ccsd.cnrs.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"

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

Vous pouvez tester les exemples suivants :

• Article dans une revue : télécharger le xml
• Thèse : télécharger le xml
• Communication : télécharger le xml
• Communication avec document : télécharger le zip
• Document non publié : télécharger le xml

Des exemples par type de document sont également disponibles sur le : dépôt Github du CCSD

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 :

• 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 réservoir accessible à RePEc dans l'archive HAL [true ou false, défaut : false]
• Hide-In-OAI : permet de cacher le dépôt du réservoir OAI-PMH et du Sitemap [true ou false, défaut : false]
• X-Allow-Completion : indique si le dépôt doit être complété [idext (récupération des métadonnées à partir d'un identifiant externe DOI, arXiv, ...), grobid (récupération des métadonnées à partir du PDF soumis via l'outil GROBID) ou affiliation (recherche des affiliations des auteurs en se basant sur le référentiel AURéHAL), les options peuvent être cumulées en les séparant par des virgules. ex: idext,affiliation]

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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.fr/sword/hal/ -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml"
        

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

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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.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

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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.fr/sword/hal-00000050 -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml"

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://halspm-api.ccsd.cnrs.fr/sword/%identifiant ressource%v%version%

Exemple :

DELETE https://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.fr/sword/hal-00000010

Une requête HTTP GET sur l'URL https://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.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://halspm-api.ccsd.cnrs.fr/sword/hal-0000002

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

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://halspm-api.ccsd.cnrs.fr/sword" version="1.0">hal@ccsd.cnrs.fr</generator>
            </source>
            <link rel="alternate" href="https://hal.archives-ouvertes.fr/hal-00000001"/>
        </entry>
    

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

Merci de contacter le support HAL pour toutes questions ou remarques