Laravel Conception de versioning de l'API RESTful
Je suis nouveau sur Laravel (4 et 5) et récemment je travaille sur une API RESTful. Afin de permettre plusieurs versions de l'API, j'utilise URL pour déterminer la version.
J'ai lu suivre ce post et il semble que la plupart des gens suivent cette approche: Comment organiser différents contrôleurs de version REST API dans Laravel 4? =
Structures des dossiers:
/app
/controllers
/Api
/v1
/UserController.php
/v2
/UserController.php
Et dans les fichiers UserController.php, je définis l'espace de noms en conséquence:
namespace Api\v1;
ou
namespace Api\v2;
et dans les itinéraires:
Route::group(['prefix' => 'api/v1'], function () {
Route::get('user', 'Api\v1\UserController@index');
Route::get('user/{id}', 'Api\v1\UserController@show');
});
Route::group(['prefix' => 'api/v2'], function () {
Route::get('user', 'Api\v2\UserController@index');
Route::get('user/{id}', 'Api\v2\UserController@show');
});
L'URL sera simple http: //..../api/v1 pour la version 1 et http: //..../api/v2 pour la version. C'est simple.
Mes questions sont les suivantes: Que se passe-t-il si je crée une mise à niveau mineure de l'API, par exemple v1.1, comment organiser ma structure de dossiers? Ma pensée était la suivante et cela devrait toujours être correct car le point est le nom valide des dossiers?
/app
/controllers
/Api
/v1
/UserController.php
/v1.1
/UserController.php
/v1.2
/UserController.php
/v2
/UserController.php
En outre, comment dois-je écrire l'espace de noms? Ce n'est pas un espace de noms comme celui-ci
namespace Api\v1.1;
Existe-t-il une convention de dénomination à laquelle je peux me référer pour utiliser "dot"?
Remarque: je ne veux pas l'appeler en tant que version v2 car il ne s'agit pas d'une mise à niveau majeure.
OMI, les mises à niveau mineures ne devraient pas publier les modifications de rupture d'une API. Donc, ma suggestion est de s'en tenir aux API versionnées entières. Les améliorations ne posent aucun problème, mais les points de terminaison existants devraient se comporter comme d'habitude.
De cette façon, vos versions d'API seraient synchronisées avec les préfixes de route et les espaces de noms ainsi que les tests.
EXEMPLE
- Vous commencez avec la v1.0
- Vous faites un petit changement (par exemple. Git-tag v1.1) qui n'apporte pas de changements de rupture à votre api. Les développeurs ont-ils besoin de faire autre chose dans leur code? Non, il n'y en a pas. Vous pouvez donc laisser en toute sécurité le préfixe URI à
V1
, pour que les développeurs qui appellent votre API n'aient pas besoin de changer tout leur code qui appelle votre API (et donc de bénéficier automatiquement de la nouvelle version mineure). Peut-être que vous venez de corriger un bogue, qui fait que leur code se comporte comme prévu ou que vous avez publié une nouvelle fonctionnalité, qui en soi ne rompt pas les appels de fonctionnalités existants. - Votre application se développe et vous publiez une nouvelle version repensée de votre API qui contient des changements de rupture. Dans ce cas, vous publiez un nouveau préfixe API-URI (
V2
).
Sachez que vous pouvez bien sûr garder une trace des versions mineures en interne (par exemple dans SCM), mais il ne devrait pas être nécessaire pour les développeurs de modifier tous leurs appels API juste pour bénéficier de ce petit bug corrigé que vous avez publié. Quoi qu'il en soit, c'est bien sûr Nice si vous informez vos clients des nouvelles versions mineures et des corrections de bugs ou améliorations qu'ils proposent (blog, newsletter, ..)
Permettez-moi d'ajouter que je ne suis au courant d'aucune API RESTful avec des préfixes d'URL d'API mineurs, donc je suppose que c'est une pratique assez courante.
Vous ne pouvez pas utiliser de points, utilisez plutôt des tirets bas.
Mais...
Une API bien conçue doit avoir BC entre les versions mineures, vous n'avez donc pas besoin de créer de nouvelle version pour une mise à jour mineure, vous devez plutôt écrire du code compatible.