Projet final : coder et publier une caisse

Introduction

L’objet de ce dernier chapitre est de conduire un projet qui pourrait être finalement publié sur le site crates.io, qui regroupe toutes les caisses Rust utilisables facilement en les déclarant dans les dépendances (dependencies) listées dans le fichier cargo.toml d’un projet Rust donné.

Plusieurs options s’offrent à nous. En effet, si l’on veut publier une caisse qui tienne un tant soit peu la route, c’est-à-dire qui puisse rendre un service effectif d’ici la fin de ce chapitre, tout en laissant la place à des évolutions et enrichissements futurs, les choix possibles sont moindres.

Une des options qui revient régulièrement dès lors que l’on réfléchit à une thématique fonctionnelle qui pourrait faire l’objet du présent chapitre est ce que l’on appelle un SDK d’API.

SDK signifie Software Development Kit et API, Application Programming Interface.

Périmètre fonctionnel

Dans le lien précédent décrivant l’API de HAL, il existe plusieurs manières d’effectuer une recherche dans cette API, qui doivent toutes, à terme, être possibles avec le SDK :

Nous allons nous limiter ici à la recherche basique qui fera l’objet exclusif de la première version publiée : la version 0.1.

Celle-ci consiste à ne pas interroger un champ précis (date, auteur, revue, etc.) mais justement à l’omettre. Ainsi, la recherche se fait sur plusieurs champs.

On peut également choisir le format de sortie : XML, JSON, CSV. Nous utiliserons le JSON.

Par exemple, la requête suivante correspond à une recherche basique du mot-clé « Europe » avec un résultat attendu en JSON :

http://api.archives-ouvertes.fr/ref/anrproject/?q=europe&wt=json 

Si on affiche le résultat de cette requête dans le navigateur, on obtient ceci :

{"response":{"numFound":149,"start":0,"docs": 
[{"docid":1776,"label_s":"L'Europe : Un ou Plusieurs Marchés  
du Travail ? [Europe] [ANR-06-JCJC-0068] [Programme \"Jeunes  
chercheuses et jeunes chercheurs\"] [JCJC]"}, 
{"docid":1636,"label_s":"Du Golfe arabo-persique à l'Europe :  
entre violences et contre-violences [Golfe-Europe] 
[ANR-06-CONF-0017] [Conflits, guerre(s)...

Développement Rust de la librairie

On commence par créer un projet de librairie :

cargo new apiarchivesouvertesrust --lib 

Puis l’idée est de décrire l’arborescence décrite plus haut. On commence par créer un objet HALDoc qui correspond à ce qui est stocké dans le tableau. On a donc le fichier haldoc.rs ci-dessous :

use std::fmt; 
use serde::{Deserialize, Serialize}; 
 
#[derive(Clone, Serialize, Deserialize, Debug)] 
pub struct HALDoc { 
 
    docid: i64, 
    label_s: Option<String>, 
    uri_s: Option<String> 
} 
 
impl HALDoc { 
 
    pub fn new( 
        docid: i64, 
        label_s: Option<String>, 
        uri_s: Option<String> 
    ) -> HALDoc { 
        HALDoc { 
            docid, 
            label_s, 
            uri_s 
        } 
    } 
 
    pub fn docid(&self) -> i64 { 
        self.docid 
    } 
 
    pub fn label_s(&self) -> Option<String> { 
        self.label_s.clone() 
    } 
 
    pub fn uri_s(&self) -> Option<String> { 
        self.uri_s.clone() 
    } 
} 
 
impl fmt::Display for HALDoc { 
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 
        write!(f, "{:?}", self) 
    } 
} 

À l’aide d’une structure...

Autres aspects et tests de la caisse

Jetons d’abord un œil au fichier cargo.toml dans lequel on doit retrouver les caisses utilisées précédemment.

On ajoute également un maximum d’informations dans les métadonnées déclarées dans le fichier cargo.toml, avec l’arrière-pensée de publier cette caisse sur crates.io :

[package] 
name = "apiarchivesouvertesrust" 
version = "0.1.0" 
edition = "2021" 
description = "Rust library that allow to access Archives ouvertes 
(HAL)." 
license = "MIT OR Apache-2.0" 
keywords = ["HAL", "archives", "ouvertes"] 
categories = ["api-bindings"] 
readme = "README.md" 
authors = ["Benoît Prieur"] 
repository = "https://github.com/benprieur/apiarchivesouvertesrust" 
homepage = "https://github.com/benprieur/apiarchivesouvertesrust" 
 
# See more keys and their definitions at https://doc.rust-lang.org/
cargo/reference/manifest.html 
 
[dependencies] 
reqwest = { version = "0.11.9", features = ["blocking"] } 
json = "0.12.4" 
serde = { version = "1.0", features = ["derive"] } 
serde_json = "1.0" 

On crée également un répertoire dédié aux tests unitaires dans lequel on crée un premier test unitaire relatif à notre recherche basique :

#[cfg(test)] 
extern crate apiarchivesouvertesrust; 
 
use apiarchivesouvertesrust::client; 
 
#[test] 
fn test_basic_search() { 
 
    let client = client::HALClient::new(); 
    let results = client.basic_search("programmation"); 
    match results { 
 
        Ok(results) => { 
            println!("Nombre de résultats : {}", results.numFound()); 
            for...

Publication de la caisse

Nous sommes à présent dans la dernière ligne droite : la publication sur crates.io.

Nous commençons par pousser le code sur GitHub. Rien d’obligatoire, mais cela permet de renseigner la métadonnée dans le fichier cargo.toml ; ainsi, l’utilisateur final aura non seulement une description de la caisse, mais également un lien vers le code :

repository = "https://github.com/benprieur/apiarchivesouvertesrust" 

Nous sommes prêts à présent pour la publication. Première étape, il vous faut créer un compte sur crates.io. Il est d’ailleurs possible d’utiliser votre compte GitHub. Il vous sera demandé par la suite de vérifier un e-mail.

Ensuite, tout se passe, comme toujours en langage Rust, avec l’outil cargo. Commencez par vous connecter en ligne de commande en indiquant un jeton (token) obtenu sur votre espace utilisateur sur le site crates.io :

cargo login abcdefghijklmnopqrstuvwxyz012345 

Puis procédez à la publication (qui se charge de recompiler le projet et de vérifier les différents aspects nécessaires à la publication) :

cargo publish 

Notez au passage cette page d’aide pour la publication des caisses : https://doc.rust-lang.org/cargo/reference/publishing.html

Tout se passe bien et la caisse est alors immédiatement disponible...