¿Cuáles son los pros y los contras con los métodos de versiones de API?

Question

En algún ejemplo, he notado dos formas de versar una API.

Uno de ellos está usando una versión en la URL

/api/v1/products

El otro es usar el encabezado de tipo de contenido y el encabezado de aceptación para marcar la versión API para el envío de datos al servidor

Content-Type=application/vnd.company.v2+xml

¿Cuáles son los pros y los contras de estos enfoques? ¿Cuáles son algún caso de uso en el que usará cada enfoque?

Answer 1

He estado acostumbrado a tener el número de versión en la URL en sí (/v1/). Personalmente, creo que este es un enfoque mucho más limpio: de esta manera, el usuario final (o desarrollador) no necesita manejar los encabezados HTTP, y simplemente puede modificar la API/llamada REST para acceder a diferentes versiones de la API según sea necesario.

Creo que también es posible que algunas de las API HTTP en diferentes idiomas no tengan soporte completo para los encabezados HTTP, por lo que siempre hace que la API esté más fácilmente disponible para el usuario final. Reescribir la URL es la forma más simple, y debería funcionar con cualquier cosa que admita HTTP.

Finalmente, permitir que la versión API se especifique utilizando la URL permite pruebas simples usando un navegador web. Si incorpora versiones en un encabezado HTTP, el desarrollador se ve obligado a usar un lenguaje de programación para realizar pruebas.

Answer 2

Ambos mecanismos son válidos. Necesita conocer a su consumidor para saber qué camino seguir. En general, trabajar con empresas y personas de mentalidad académica tiende a señalar a los desarrolladores hacia la versión de encabezado de recursos. Sin embargo, si sus clientes son empresas más pequeñas, el enfoque de versiones de URL se usa más ampliamente.

Aquí están los pros y los contras que pude encontrar (estoy seguro de que hay más, y algunas de las desventajas tienen trabajo no mencionados aquí)

1. Es más explorable. Para la mayoría de las solicitudes, puede usar un navegador, mientras que la implementación del encabezado de recursos requiere un enfoque más programático para las pruebas. Sin embargo, debido a que no todas las solicitudes HTTP son explorables, por ejemplo, solicitudes de publicación, debe usar un complemento de cliente REST como Cartero o Pata. Uri Pro/Header Con

2. Con una API aversiones de URI, la identificación de recursos y la representación del recurso se unen. Esto viola los principios básicos de descanso; Un recurso debe ser identificado por un solo punto final. En este sentido, la elección de versiones de encabezado de recursos es más académicamente idealista. Encabezado Pro/Uri Con.

3. Una API aversiones de URI es menos propensa a errores y más familiar para los desarrolladores de clientes. El verso por URL permite al desarrollador descubrir la versión de un servicio de un vistazo. f El desarrollador del cliente olvida incluir una versión de recursos en el encabezado, debe decidir si debe dirigirse a la última versión (que puede causar errores al incrementar la versión) o un error 301 (movido permanente). De cualquier manera, hay más confusión para sus desarrolladores de clientes más novatos. Uri Pro/Header Con
4. URI Versión se presta para manejar múltiples versiones en la misma aplicación. En este caso, no tiene que desarrollar más su marco. Nota: Si hace esto, su estructura de directorio probablemente contenga una cantidad sustancial de código duplicado en el directorio V2. Además, la implementación de actualizaciones requiere un reinicio del sistema, por lo tanto, esta técnica debe evitarse si es posible. Uri Pro/Header Con.
5. Es más fácil agregar versiones a los encabezados HTTP para un proyecto existente que no tenía versiones en mente desde su inicio. Encabezado Pro/Uri Con.
6. De acuerdo con la Principio de descanso de nivel 3 de RMM: controles de hipermedia, debe usar los encabezados HTTP Acepts y Type-Type para manejar la verificación de los datos y describir los datos. Encabezado Pro/Uri Con.
7. Cuando coloca la versión en la URL, sus clientes deben coordinar un cambio de su código (o si son inteligentes, su configuración), a la nueva API. Encabezado Pro/Uri Con.

Aquí hay algunos enlaces útiles si desea leer más:

• Descripción de Martin Fowler del modelo de madurez de Richardson
• Versiones API - Laboratorios fundamentales
• Hateaos
• El artículo de Informit.com sobre los servicios de REST de versiones

Answer 3

Es mejor usar la versión en URL. Estaba buscando esto hace un tiempo y encontré los siguientes 2 recursos que discuten Diseño de API RESTful en longitud.

1. Las mejores prácticas para diseñar una API pragmática RESTful - Versión a través de la URL, no a través de encabezados.
2. programadores.stackexchange.com : ¿Cuál es un patrón recomendado para la planificación de puntos finales REST para cambios previsibles?

Tl; dr respuesta: Usar la versión # en la URL es un enfoque recomendado.

Algunos de los API más diseñados que he encontrado, API de Instagram y Stackoverflow.com API - Ambos usan este enfoque para la versiones de API.