REST
==========


Scripts pour se connecter à l’API WoS (Web of Science) pour l’interroger et télécharger un corpus de notices, au format JSON ou au format XML,  en utilisant 
le protocole [REST](https://fr.wikipedia.org/wiki/Representational_state_transfer). Il n’y a pas de session à proprement parler, mais se passe en 2 étapes 
avec un script `bash` dédié pour chacune de ces étapes : 


| Étapes | Scripts |
| ------ | ------- |
| Interrogation de l’API | `WosQuery.sh` |
| Téléchargement des notices | `WosRetrieve.sh` |


Dans le cas particulier d’une recherche à partir d’une liste de DOIs, on utilise le script `rWosSearchByDoi.sh` qui fait à la fois l’interrogation de l’API et le téléchargement des notices, remplaçant ainsi les scripts `rWosQuery.sh` et `rWosRetrieve.sh`.  

Ces scripts ont besoin pour fonctionner de trois programmes qui sont généralement présents dans les distributions Unix/Linux :

 - `curl`
 - `jq`
 - `xmllint`

Pour tous ces scripts, toutes les informations renvoyées par le programme `curl` sur la sortie standard ou sur l’erreur standard sont conservées dans deux fichiers, 
respectivement `WosApiOut.json` ou `WosApiOut.xml` (suivant le format des notices), et `WosApiErr.txt`.


## rWosQuery.sh

Ce script permet l’interrogation de l’API WoS à l’aide d'une clé chiffrée. Par souci de sécurité, il n’y a pas d’option pour la clé en ligne de commande. 
Elle sera demandé par la suite de façon plus sûre. Par défaut, l’interrogation se fait sur l’ensemble des bases WoS et retourne un numéro de requête (*queryId*), 
le nombre de notices trouvées, le nombre total de notices dans les bases WoS interrogées ainsi que 5 notices complètes. 
Il est possible de limiter la recherche à certaines bases WoS avec l’option “-b”, on peut choisir de ne garder que certains champs dans les notices grâce à l’option “-f” 
et on peut modifier l’ordre de tri des notices avec l’option `-t`. 


### Usage

```bash
    rWosQuery.sh -q 'requête' [ -r (résultats|-) ] [ -n nb_notices ]
                 [ -[cmp] début:fin ] [ -l [0-9]+[DWMY] ] [ -b [WOS:]base ]*
                 [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ]
                 [ -j cookie_jar ] [ -ix ]
    rWosQuery.sh -h
```

À noter que les options `-c`, `-l`, `-m` et `-p` be sont pas compatibles entre elles et on ne peut en utiliser 
au plus qu'une seule. Les valeurs possibles pour les options `-b`, `-f` et `-t`  sont données dans les [tables WoS](https://gitbucket.inist.fr/tdm/api-wos#tables-wos) 
de la page rincipale.


### Options principales

```txt
    -c  limite la recherche dans la base de données aux dates de création
        des notices indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par
        exemple, “2000-01-01:2020-07-31”)
    -h  affiche cette aide
    -l  limite la recherche dans la base de données aux dates de chargement
        des notices indiquées sous la forme d’un nombre de jours (D), de
        semaines (W), de mois (M) ou d’années (Y). Les valeurs acceptées vont
        de “0D” à “6D”, de “1W” à “52W”, de “1M” à “12M” et de “0Y” à “10Y”
    -m  limite la recherche dans la base de données aux dates de modification
        des notices indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par
        exemple, “2000-01-01:2020-07-31”)
    -p  limite la recherche dans la base de données aux dates de publication
        indiquées sous la forme aaaa-mm-jj:aaaa-mm-jj (comme par exemple,
        “2000-01-01:2020-07-31”)
    -r  indique le nom du fichier où placer les notices téléchargées (mettre
        un tiret pour indiquer la sortie standard)
    -q  fournit la requête à envoyer (entre simples ou doubles quotes si
        elle contient des espaces ou des caractères spéciaux)
    -x  indique que les notices doivent être en XML au lieu de JSON, le format
        par défaut
```


### Autres options

```txt
    -b  limite la recherche à une ou plusieurs bases (e.g. “WOS:SCI”).
        Cette option est répétitive et “WOS:” est facultatif (par défaut,
        la recherche se fait sur l’ensemble du WoS)
    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées (5 par défaut ou valeur de l’option “-n”)
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -n  indique le nombre de notices, entre 0 et 100, à retourner (5 par
        défaut)
    -t  trie les résultats sur un champ (nom abrégé à 2 majuscules) de
        façon croissante (A) ou décroissante (D) ou par pertinence (RS)
        forcément décroissante
```


## rWosRetrieve.sh

Ce script permet de télécharger les notices trouvées lors de l’interrogation de l’API WoS en utilisant la clé d’identification 
(demandée hors ligne de commande, par sécurité) et le numéro de requête (*queryId*) obtenu à l’étape précédente. 
En cas d’interruption du transfert, il est possible de reprendre le téléchargement là où il s'est arrêté en indiquant un nouveau numéro de départ (option “-o”). 
Si vous avez utilisé les options `-f` et/ou `-t` lors de l’interrogation de l’API, vous devez utiliser les mêmes options avec les mêmes valeurs pour 
décharger le corpus de notices
Si vous recevez un message signalant une limitation de la bande passante (*bandwidth throttling*), vous pouvez modifier le délai entre deux itérations 
(1 seconde par défaut) avec la variable d’environnement `WOS_DELAY`. Par exemple, pour passer à un délai de 3 secondes : 

```bash
    export WOS_DELAY=3
```


### Usage

```bash
    rWosRetrieve.sh -q queryId -n nb_notices -r (résultats|-) [ -o offset ] 
                    [ -f champs ]* [ -t CH:(A|D)[,CH:(A|D)]* ]
                    [ -j cookie_jar ] [ -ix ]
    rWosRetrieve.sh -h
```

### Options

```txt
    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -h  affiche cette aide
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
        par défaut)
    -n  indique le nombre total de notices WoS à télécharger (la valeur
        maximale est donnée par le programme envoyant la requête à l’API
        WoS)
    -o  indique à partir de quel numéro (offset), on veut télécharger les
        notices, en particulier pour reprendre un téléchargement après un
        problème de connexion (1 par défaut)
    -q  indique le numéro de la requête “queryId” dont on veut télécharger
        les résultats
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -t  trie les résultats sur un champ (nom abrégé à 2 majuscules) de
        façon croissante (A) ou décroissante (D) ou par pertinence (RS)
        forcément décroissante
    -x  indique que les notices doivent être en XML au lieu de JSON, le format
        par défaut
```


## rWosSearchByDoi.sh (en cours de réécriture)

Ce script permet à la fois l’interrogation de l’API WoS à partir d’une liste de DOIs et le téléchargement des notices trouvées en utilisant la clé d’identification. 
Contrairement au script `rWosQuery.sh`, on n’a pas d’options pour limiter la recherche par période ou par base. On n’a pas non plus d’option de tri parce que la 
recherche se fait par paquet de 100 DOI maximum et le tri se ferait au sein de chaque paquet au lieu de se faire sur l’ensemble du corpus. 
En fait, on récupère les notices dans l’ordre des DOI. 


### Usage

```bash
    rWosSearchByDoi.sh -d (fichier|-) -r (résultats|-) [ -f champs ]*
                       [ -j cookie_jar ] [ -ix ]
    rWosSearchByDoi.sh -h
```

### Options principales 

```txt
    -d  indique le nom du fichier avec la liste des DOIs à chercher. Si on
        a un tiret “-” en argument, la liste de DOIs est lue sur l’entrée
        standard
    -f  limite les champs présents dans les notices téléchargées. Cette
        option est répétitive (par défaut, tous les champs sont présents)
    -h  affiche cette aide
    -i  ajoute dans la réponse de l’API la liste des identifiants WoS des
        notices retournées
    -j  indique le nom du fichier qui recevra les cookies (“cookies.txt”
    -r  indique le nom du fichier résultat (pour la sortie standard, utiliser
        le tiret “-” comme argument de l’option)
    -x  indique que les notices doivent être en XML au lieu de JSON, le format
        par défaut
```