web-dev-qa-db-fra.com

Comment gérez-vous la version api dans une application Node / Express

Je suis assez nouveau sur Node.js et je suis confronté au problème suivant.

Mon middleware a commencé avec le lien api/v1/login et un tas de points de terminaison. Alors api/v1.1 a introduit 2 autres points de terminaison. api/v1.2 est maintenant le dernier et a obtenu de nouveaux points de terminaison.

Comment dois-je gérer cette version d'API de manière efficace? Comment rendre les points de terminaison d'une version disponibles aux versions suivantes également?

node.jsapiexpressversioning
30
Paolo.nl

Tout d'abord, si vous construisez une REST et que vous venez de commencer, vous pouvez envisager d'utiliser Restify au lieu d'Express. Alors qu'Express peut certainement être utilisé à cet effet, Restify a été conçu avec toutes les exigences pour un serveur API REST: exceptions standardisées, versionnage API, etc.

Ainsi dit, je crois que votre premier problème est un défaut de conception. Vous devez créer des points de terminaison distincts uniquement lorsque les nouvelles API ne sont pas pas rétrocompatibles avec la version précédente, c'est-à-dire lorsque la version principale est augmentée (par exemple à partir de v1 à v2). Cela devrait arriver aussi rarement que possible!
Si vous ajoutez uniquement de nouvelles fonctionnalités ou apportez d'autres modifications qui ne cassent pas le code existant, vous ne devez pas créer de point de terminaison différent. Donc, vous ne devez pas créer de points de terminaison pour v1.1, v1.2, etc., à condition que tout le code qui fonctionne avec v1.0 fonctionne également avec v1.1 (si ce n'est pas le cas, vous introduisez des changements qui ne sont pas rétrocompatibles, et vous devriez donc envisager de changer la version en v2).
Notez que chaque fois que vous introduisez des modifications rétro-incompatibles, tous vos utilisateurs devront mettre à jour leur code, et vous devrez prendre en charge les anciennes API pendant une période suffisante pour permettre à tous vos utilisateurs de se mettre à jour. C'est un processus coûteux, pour vous (vous devez conserver les anciennes bases de code) ainsi que pour vos utilisateurs (ils doivent mettre à jour leur code), et devrait donc se produire aussi rarement que possible. De plus, pour chaque version, vous devez rédiger de la documentation, créer des exemples, etc.
(Conclusion: passez beaucoup de temps à concevoir votre serveur API afin qu'il durera probablement sans modifications incompatibles en amont aussi longtemps que possible)

Pour répondre à votre question, alors, un moyen de le faire pourrait être de créer des sous-dossiers pour chaque ensemble d'API (chaque version), puis de configurer le routeur en conséquence. Par exemple, votre projet ressemblera à:

/
-- app.js
-- routes/
-- -- v1/
-- -- -- auth.js
-- -- -- list.js
-- -- v2/
-- -- -- auth.js
-- -- -- list.js

Cela ne devrait pas poser de problème: puisque la v2 n'est pas rétrocompatible avec la v1, il est probable que les deux fichiers soient très différents.
Ensuite, sur Express, utilisez simplement le routeur en conséquence. Par exemple:

app.get('/v1/list/:id', v1.list)
app.all('/v1/auth', v1.auth)

app.get('/v2/list/:id', v2.list)
app.all('/v2/auth', v2.auth)

Il existe cependant d'autres options. Par exemple, une solution plus élégante (quoique légèrement avancée) peut être: http://j-query.blogspot.ca/2013/01/versioned-apis-with-express.html

Remarque sur cette méthode

Alors que, comme par semver, chaque modification incompatible en amont devrait voir une augmentation de la version principale des API, si vous prévoyez d'implémenter de nombreuses différences substantielles entre v1 et v2 (avec très peu de possibilité de réutiliser le code), alors ceci l'approche n'est pas pour vous.

Dans ce dernier cas, vous souhaiterez peut-être créer deux applications Node.js distinctes pour v1 et v2, puis configurer le routage approprié à l'aide de nginx. Le contrôle de version ne se fera pas au niveau de l'application (chaque application répondra à '/ auth', '/ list /: id' et NON '/ v1/auth', '/ v1/list: id', etc.), mais à nginx transmettra les demandes avec le préfixe '/ v1 /' à un serveur de travail et celles avec le préfixe '/ v2 /' à l'autre.

49
ItalyPaleAle

Les cadres comme restify sont mieux adaptés au versionnage api, mais si vous utilisez express et avez besoin d'un module léger pour versionner vos itinéraires, essayez ce module npm https://www.npmjs.com/package/express-routes- versioning

Le module permet aux itinéraires individuels d'être versionnés séparément. Il prend en charge le versionnement de base de semver sur le serveur pour correspondre à plusieurs versions. (si besoin). Il est indépendant des stratégies de version spécifiques et permet à l'application de définir la version.

Exemple de code

var app = require('express')();
var versionRoutes = require('express-routes-versioning')();
app.listen(3000);
app.use(function(req, res, next) {
    //req.version is used to determine the version
   req.version = req.headers['accept-version'];
   next();
});
app.get('/users', versionRoutes({
   "1.0.0": respondV1,
   "~2.2.1": respondV2
}));

// curl -s -H 'accept-version: 1.0.0' localhost:3000/users
// version 1.0.0 or 1.0 or 1 !
function respondV1(req, res, next) {
   res.status(200).send('ok v1');
}

//curl -s -H 'accept-version: 2.2.0' localhost:3000/users
//Anything from 2.2.0 to 2.2.9
function respondV2(req, res, next) {
   res.status(200).send('ok v2');
}
11
prasanna ramanujam