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

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.

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 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.3 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.4 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éral 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.4.1 Le dépôt de documents

Dans le cas d'un dépot 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 test_ws:test https://api-preprod.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.4.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 test_ws:test https://api-preprod.archives-ouvertes.fr/sword/hal/ -H "Packaging:http://purl.org/net/sword-types/AOfr" -H "Content-Type:text/xml"
        

3.5 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 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

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

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 test_ws:test https://api-preprod.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 test_ws:test https://api-preprod.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 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>
    

9. Questions ?

Merci de contacter le support HAL pour toutes questions ou remarques