Le blog

Sortie de Vulcain 1.0 !

Publié le 19 octobre 2023

Traduction de https://github.com/dunglas/vulcain

Nous sommes très heureux d’annoncer la disponibilité immédiate de la version 1.0 de Vulcain !

Vulcain est un protocole utilisant les Preload Hints, le code de statut HTTP 103 Early Hints ou HTTP/2 Server Push pour créer des API REST pilotées par les clients. Un serveur de passerelle Open Source que vous pouvez placer devant toute API Web existante pour la rendre instantanément compatible avec Vulcain est également fourni. Vulcain supporte les APIs hypermédias mais aussi toute API “legacy” en documentant ses relations à l’aide d’OpenAPI.

Schema du fonctionnement du protocole Vulcain" class="wp-image-7911" style="aspect-ratio:4/3;object-fit:cover

Ce protocole est maintenu dans ce dépôt Github. Un serveur passerelle de référence, prêt pour un déploiement en production, est également disponible. C’est un logiciel libre (AGPL) écrit en Go et basé sur le serveur web Caddy. Une image Docker est fournie.

Introduction au protocole #

Au fil des années, plusieurs formats ont été créés pour résoudre les problématiques de performance impactant les APIs : l’over fetching, l’under fetching, le problème N+1... Les solutions actuelles pour contourner ce problème (GraphQL, ressources intégrées, sparse fieldsets de JSON:API…) sont des network hacks pour HTTP/1 qui présentent (trop) d'inconvénients en ce qui concerne le cache HTTP, les logs et même la sécurité.

Heureusement, grâce aux nouvelles fonctionnalités introduites dans la plateforme web, il est maintenant possible de créer de véritables API REST corrigeant ces problèmes avec facilité. C’est là que Vulcain entre en jeu ! Découvrez en version originale la comparaison entre Vulcain et GraphQL, et d'autres formats API.

Pousser des relations #

Schema du fonctionnement du protocole Vulcain" class="wp-image-7913" style="aspect-ratio:4/3;object-fit:cover

Considérons les ressources suivantes :

/books

{
    "member": [
        "/books/1",
        "/books/2"
    ]
}

/books/ 1

{
    "title": "1984",
    "author": "/authors/1"
}

/books/ 2

{
    "title": "Homage to Catalonia",
    "author": "/authors/1"
}

/authors/1

{
    "givenName": "George",
    "familyName": "Orwell"
}

L'en-tête HTTP Preload introduit par Vulcain peut être utilisé pour demander au serveur de pousser immédiatement les ressources liées à celle demandée en utilisant les Preload Hints (avec ou sans le code HTTP 103) ou le Server Push d’HTTP/2 :

GET /books/ HTTP/2
Preload: "/member/*/author"

En plus de /books/, un serveur Vulcain utilisera le Server Push HTTP/2 pour pousser les ressources /books/1, /books/2 et /authors/1 ! Voici un exemple en JavaScript :

const bookResp = await fetch("/books/1", { headers: { Preload: `"/author"` } });
const bookJSON = await bookResp.json();

// Retourne immédiatement, la ressource a été poussée et se trouve déjà dans le cache de push
const authorResp = await fetch(bookJSON.author);
// ...

Voici l’exemple complet, incluant les collections. Voir aussi comment utiliser GraphQL comme langage de requête pour Vulcain.

Grâce au multiplexage HTTP/2 et 3, les réponses poussées seront envoyées en parallèle.

Lorsque le client suivra les liens et émettra une nouvelle requête HTTP (par exemple en utilisant  fetch()), la réponse correspondante sera déjà en cache, et sera utilisée instantanément !

Pour les APIs non hypermédia (lorsque l'identifiant de la ressource concernée est une simple chaîne de caractères ou un entier), vous pouvez utiliser une spécification OpenAPI pour configurer les liens entre les ressources. Autre conseil : la façon la plus simple de créer une API hypermédia est d'utiliser le framework API Platform dont nous sommes également les créateurs. 
Vulcain génère automatiquement  vers des liens preload, qui peuvent être utilisés avec le code HTTP 103, et peut utiliser Server Push.

Paramètre de requête #

Alternativement aux en-têtes HTTP, le paramètre de requête preload peut être utilisé :