¿Cuál es la estructura de archivo de proyecto correcta para una API de descanso versionada?

7

Debería tener directorios de recursos dentro del directorio de la versión, como

app/
  v1/
   book/
   author/
  v2/
   author/

o directorios de versión dentro de la carpeta de recursos

app/
  book/
    v1/
  author/
    v1/
    v2/

¿Cuál sería más fácil de mantener y cuál se usa comúnmente hoy?

    
pregunta ivan.c 12.04.2015 - 12:37

2 respuestas

3

La forma más común: creo que es la "versión primero, recursos dentro". Al menos lo he visto en las API de diferentes redes sociales. Y nunca he visto de otra manera.

Es la única forma lógica de dos: hay recursos dentro (diferentes versiones de) de su API, no API dentro de los recursos. Es más fácil eliminar las versiones anteriores de esa manera: solo responda con 404 en las solicitudes de todos los sub-recursos, proporcionando un mensaje como "Esta versión de API ya no existe" , lo que deja claro que No es sólo un error tipográfico en la URL. Por esa razón, creo que también es mucho más fácil de mantener, al menos en los marcos que he usado: simplemente agregaría otra regla en mi enrutador, que coincide con todas las versiones anteriores y responde correctamente.

Por lo tanto, en mi experiencia, la primera versión (la primera versión, los recursos internos) es la única que he visto que se usa, y es mucho más fácil de mantener.

El control de versiones basado en encabezado (por ejemplo, Accept: application/vnd.service.v2+json ) es muy diferente del anidamiento de URL: la creación de versiones de una API completa frente a la creación de versiones de una sola entidad. Los cambios en la API pueden incluir agregar, mover y eliminar recursos, lo que no es algo que pueda describirse de manera efectiva utilizando una versión de entidad.

También, REST requiere HATEOAS (consulte Richardson Maturity Model para una explicación más detallada de esto), que sería difícil (o imposible) de implementar con el control de versiones basado en encabezados. Por ejemplo, ¿es incluso posible ajustar versiones basadas en encabezado en HAL ? Tendría que inventar una forma de agregar una versión a los enlaces, lo que probablemente requeriría un formato personalizado (no URL).

Algunas personas piensan que lo contrario es cierto , pero aún no estoy de acuerdo, porque no se trata de versionar recursos, sino de versionando toda la API. Todos los recursos dentro de cada versión de una API tienen la misma versión, sin importar si esos recursos son los mismos que en las versiones anteriores.

    
respondido por el scriptin 12.04.2015 - 14:47
1

Espero que no confunda el patrón de URL con el sistema de archivos.

El patrón de URL es algo flexible y donde (y cómo) su código fuente está escrito o estructurado es completamente diferente.

No debes confundir los dos.

En cuanto a la convención, es común usar el controlador de versión antes del nombre del recurso (o colección): http://www.example.com/api/v1/books/ , por ejemplo. Esta es la mejor práctica demostrada por la mayoría de las aplicaciones públicas de REST. También puede elegir la versión de su API de manera diferente; por ejemplo, api/2014-01/books/ o api/1.0.1/books etc.

La excepción notable es facebook, que tiene la versión como parámetro opcional a la URL, ?v=1 .

Debes mantener el número de versión lo más a la izquierda posible del URI, ya que esto le otorga el mayor alcance.

En cualquier caso, siempre debe documentar adecuadamente sus versiones de API y, si hay un cambio incompatible con versiones anteriores, documéntelo y dé a sus desarrolladores la oportunidad de migrar.

    
respondido por el Burhan Khalid 12.04.2015 - 14:46

Lea otras preguntas en las etiquetas