php - guía - Diseño de control de versiones de API RESTful de Laravel

laravel api routes

Question

Soy nuevo en Laravel (4 y 5) y recientemente estoy trabajando en una API RESTful. Para permitir la versión múltiple de la API, estoy usando la URL para determinar la versión.

Leí seguir esta publicación y parece que la mayoría de la gente sigue este enfoque: ¿cómo organizar diferentes controladores REST API versionados en Laravel 4?

Estructuras de carpetas:

/app
  /controllers
    /Api
      /v1
        /UserController.php
      /v2
        /UserController.php

Y en los archivos UserController.php configuré el espacio de nombres en consecuencia:

namespace Api/v1;

o

namespace Api/v2;

y en rutas:

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'');
});

La URL será simple http: //..../api/v1 para la versión 1 y http: //..../api/v2 para la versión. Esto es sencillo.

Mi pregunta es: ¿qué sucede si estoy compilando una actualización menor de api, digamos v1.1, cómo organizo la estructura de mi carpeta? Mi pensamiento era este y debería estar bien, ya que el punto es el nombre válido de las carpetas.

/app
  /controllers
    /Api
      /v1
        /UserController.php
      /v1.1
        /UserController.php
      /v1.2
        /UserController.php
      /v2
        /UserController.php

Además, ¿cómo debería escribir el espacio de nombres? Este no es un espacio de nombres como este

namespace Api/v1.1;

¿Hay una convención de nombres a la que pueda referirme para usar "punto"?

Nota: No quiero llamarlo como versión v2 porque esta no es una actualización importante.

Answer 1

IMO, las actualizaciones menores no deberían publicar cambios de última hora en una API. Por lo tanto, mi sugerencia es mantener las API de versiones enteras. Las mejoras no son un problema, pero los puntos finales existentes deberían comportarse como siempre.

De esta forma, sus versiones de API estarían sincronizadas con los prefijos de ruta, los espacios de nombres y las pruebas.

EJEMPLO

1. Usted comienza con v1.0
2. Haces un pequeño cambio (por ejemplo, git-tag v1.1) que no trae cambios de última hora a tu API. ¿Hay una necesidad de que los desarrolladores hagan algo más en su código? No no hay. Así que puedes dejar que el prefijo URI permanezca en V1 , de modo que los desarrolladores que llamen a tu API no necesiten cambiar todo el código que llama a tu API (y, por lo tanto, se beneficiará automáticamente de la nueva versión secundaria). Tal vez haya solucionado un error, lo que hace que su código se comporte como se esperaba o que haya publicado una nueva característica, que por sí sola no interrumpe las llamadas a funciones existentes.
3. Su aplicación crece y publica una nueva versión rediseñada de su API que contiene cambios importantes. En este caso, publica un nuevo API-URI-prefix ( V2 ).

Tenga en cuenta que puede, por supuesto, realizar un seguimiento de las versiones menores internamente (por ejemplo, en SCM), pero no debería haber necesidad de que los desarrolladores cambien todas sus llamadas API solo para beneficiarse de esa pequeña corrección de errores que ha publicado. De todos modos, es bueno, por supuesto, si notifica a sus clientes las versiones menores más recientes y las correcciones de errores o mejoras que ofrecen (blog, boletín, ...)

Permítanme agregar, que no conozco ninguna API RESTful con menores API-URL-prefijos, así que supongo que esta es una práctica bastante común.

Answer 2

No puede usar puntos, use guiones bajos en su lugar.

Pero...

Una API bien diseñada debe tener BC entre versiones menores, por lo que no necesita crear una nueva versión para una actualización menor, en su lugar debe escribir un código compatible.