Versioning API REST de una aplicación ASP.NET MVC

Question

Estoy buscando desarrollar una aplicación en ASP.NET MVC 3 y me gustaría proporcionar una API pública al mismo tiempo.

Al mirar a su alrededor, parece haber 2 formas de hacerlo. Cree un área de API y tenga controladores que devuelvan json/xml. O use filtros de acción y un único conjunto de controladores frontales, y devuelva json/xml/html según los encabezados de las solicitudes.

Me gustaría hacerlo más tarde, pero me preguntaba cómo podría hacer para versionar su API si fuera por esta ruta.

Si vas por la primera ruta, puedes simplemente crear un controlador v1/v2, pero si lo haces más tarde, ¿cómo podrías versionarlo?

Answer 1

Puede hacer una de estas dos rutas: puede incluir la API en la ruta (en lugar de http://app.lication/category/1 tendría algo así como http://app.lication/api/v1/category/1) o podría incluir un custom HTTP header.

Cualquiera de los dos le permitirá discriminar a qué versión se llama.

Answer 2

El control de versiones es un problema bastante complejo para empezar. He aquí algunas maneras en las que miré antes:

1. URL. En este caso, se supone que https://api.example.com/v1/projects es un recurso diferente de http://api.example.com/v2/projects, aunque no es el caso. Basecamp parece hacer esto. Siguiendo este enfoque, suponga que siempre tendrá que admitir API antiguas.
2. Encabezados. Las URL siguen siendo las mismas, sin embargo, el cliente pasa un encabezado HTTP adicional, digamos X-MYAPI-VERSION con cada solicitud con un valor que identifica la versión de la API que se va a usar. El Google Documents List API hace esto. Un problema potencial con este enfoque es que los encabezados HTTP pueden ser eliminados por intermediarios entre el cliente y el servidor.
3. Parámetros. Para evitar el problema con la opción 2, puede pasar la versión de la API para utilizarla como parámetro (como https://api.example.com/projects?v=3).
4. Tipos de medios. Aquí sus URL permanecen iguales, sin embargo, se requiere que los usuarios especifiquen la representación de los recursos usando los encabezados de aceptar y de tipo de contenido. Por ejemplo, un "proyecto" se puede presentar usando "application/vnd.mycompany.resource [-version] [+ format]" dando sus representaciones de "application/vnd.mycompany.project-v1 + json" para v1 json o " application/vnd.mycompany.project-v1 + xml "para v1 xml. Cuando necesite una nueva versión de un proyecto, el tipo de mime se verá como sigue "application/vnd.mycompany.project-v2 + xml". Github parece apoyar eso.
5. Parte de la carga útil. En este caso, la carga útil de la solicitud contiene el número de versión que se utilizará. Por ejemplo, cuando se pasa XML, puede mirar el espacio de nombres para determinar qué versión de la API se está utilizando. Para JSON, puede usar una propiedad "$ version" o "_version" para especificar la versión.
6. Clave de cliente. Cuando la aplicación se registra, especifica qué versión de la API quiere usar. Cuando autentica al cliente, se asegura de que emule la versión que quiere usar.
7. Sin versiones explícitas Siempre existe la opción de no versionar su API y tratar de manejar los cambios de forma transparente haciendo que todos los campos sean opcionales y los maneje apropiadamente cuando faltan. Lo más probable es que lo haga de todos modos para que las versiones futuras de su API sean compatibles con la versión que está desarrollando actualmente.

Muchos recomiendan la opción 4, aunque no siempre es práctica. La mayoría de estas opciones requieren trabajo adicional para trabajar con ASP.NET MVC.