Tengo una API ASP.NET Core 3.1 y presento una nueva versión para uno de mis controladores. Estoy usando el paquete Microsoft.AspNetCore.Mvc.Versioning NuGet y configuré la nueva versión como la versión predeterminada. Todos mis otros controladores deberían funcionar tanto con la versión anterior (1.0) como con la nueva versión (1.1).
Por ejemplo:
[ApiVersion("1.0", Deprecated = true)] public class MySampleController { } [ApiVersion("1.1")] public class MyNewSampleController { } [ApiVersion("1.0", Deprecated = true)] [ApiVersion("1.1")] public class AllOtherController { } Preguntas:
¿Realmente tengo que agregar todas las versiones a todos los controladores?
¿Hay una forma mejor/correcta de manejar esto?
He intentado usar [ApiVersionNeutral] pero eso no parece correcto y, según la documentación , solo debe usarse en casos especiales. Si no agrego el atributo [ApiVersion], el valor predeterminado es la nueva versión 1.1 y la 1.0 ya no funciona.
Dado que esta es mi primera pregunta SO, espero que se ajuste a las pautas :)
P: ¿Realmente tengo que agregar todas las versiones a todos los controladores?
R: Sí. Las versiones de API son discretas. Un cliente debe obtener exactamente lo que solicita y una respuesta de error adecuada si el servidor no puede satisfacer la solicitud.
P: ¿Hay una forma mejor/correcta de manejar esto?
R: Hay varias opciones posibles. Una forma mejor o más correcta de manejar las cosas es muy subjetiva. Existen numerosos factores y la decisión final puede simplemente reducirse a la preferencia.
Un concepto erróneo común es que el control de versiones de la API utiliza atributos. Realmente no le importan los atributos, es solo una posibilidad y una que tiende a resonar con los desarrolladores como metadatos. Tiene la opción de usar atributos listos para usar, atributos personalizados, convenciones listas para usar o sus propias convenciones personalizadas.
La elección de cómo aplicar los metadatos de la versión suele ser una preferencia y una gestión práctica. Un escenario común es organizar los controladores en carpetas por versión de API. En varios lenguajes .NET, el nombre de la carpeta se traduce como parte o la totalidad del espacio de nombres correspondiente. Esta disposición es lo suficientemente común como para que exista una convención VersionByNamespace lista para usar. Para obtener más información, consulte la documentación . El ejemplo Por espacio de nombres también demuestra cómo mejorar un proyecto de este tipo de principio a fin.
Versión neutral de API significa que una API toma todas y cada una de las versiones, incluida ninguna. Puede significar que no te importa la versión de la API o que aceptas un rango completo que manejarás tú mismo. En realidad, solo está destinado a usarse con API que nunca cambian con el tiempo. Por ejemplo, una operación HTTP DELETE normalmente no cambia con el tiempo o entre versiones.
No está 100% claro lo que quieres decir con:
"Si no agrego el atributo [ApiVersion], el valor predeterminado es la nueva versión 1.1 y la 1.0 ya no funciona".
No hay valores predeterminados per se. Esta declaración parece implicar que ha establecido la opción AssumeDefaultVersionWhenUnspecified en true . No debe hacer eso a menos que tenga una muy buena razón para hacerlo. Esa es probablemente una de las características más abusadas del control de versiones de API. Un cliente debe conocer la versión que está solicitando. Permitir que un cliente no especifique una versión y hacer que las cosas pasen de 1.0 a 1.1 puede romper el cliente. El servidor no puede suponer que no lo hará. Esta característica estaba pensada para ser utilizada en los servicios existentes que no tenían previamente definida una versión explícita. Ese escenario solo existe cuando el control de versiones de API se habilita por primera vez. Como se indicó anteriormente, todos los controladores deben tener una o más versiones discretas de API, pero el conjunto original de API no lo tenía definido explícitamente. Si esta función no existiera, el conjunto de referencia de clientes que no sabían acerca de una versión de API se rompería.