1. REST API Versioning Techniques
Arquitecto de Soluciones de Software
Rodrigo Liberoff
with ASP.NET Web API

2. “Si al principio no tienes
éxito, llámalo versión 1.0.”
― Anónimo - Desconocido

3. Introducción

5. Google
Youtube
Facebook
Wikipedia
TwitterLinkedIn
Wordpress
Yahoo
El Mundo

6. El desarrollo de Web APIs está explotando…

7. …y las compañías están exigiéndolo.

9. Los creadores de HTTP pensaron mucho sobre esto y
sobre cómo diseñar con miras a la evolución.

11. La pregunta no es “si evoluciona”...
…la pregunta es “cómo evolucionará”.

14. Conceptos

15. ¿QUÉES…?

16. ¿QUÉES…?

17. ¿QUÉES…?

18. ¿QUÉES…?

19. ¿QUÉES…?

20. Ejemplo

21. Ejemplo

22. ¿QUÉSON…?

23. Ejemplos

24. ¿QUÉES…?

29. http://geek-and-poke.com/geekandpoke/2013/6/14/insulting-made-easy

30. ¿QUÉES…?

31. ¿QUÉES…?

32. Versionando un Web API

38. En general, se considera que la combinación de
descubrimiento de recursos en tiempo de ejecución,
mensajes auto-descriptivos y clientes reactivos son críticos
para conseguir un Web API evolucionable.
También se considera que, aunque son conceptos difíciles
de entender e implementar, la flexibilidad y escalabilidad
que aportan supera con creces su costo.

39. En general, en la filosofía REST, versionar recursos se
considera una mala práctica o evidencia de un pobre
diseño.

41. TIPO DESCRIPCIÓN
Payload La versión es parte del mensaje.
Query String
La versión es un parámetro que forma parte de la URI
del recurso.
URL Suffix
La versión es parte del URI, y se anexa al final del
mismo.
Custom Header
La versión es suministrada en una cabecera propia no
estándar.
URL La versión es parte indirecta del URI del recurso.
Media Type
Content Type
La versión es suministrada como el media type
esperado de la representación del recurso.
TIPO DESCRIPCIÓN
Payload La versión es parte del mensaje.
Query String
La versión es un parámetro que forma parte de la URI
del recurso.
URL Suffix
La versión es parte del URI, y se anexa al final del
mismo.

43. Ejemplos
<xml>
<version>2</version>
...
</xml>
http://MyCoolSite/api/recurso?v=2
http://MyCoolSite/api/recurso?v=1_1
http://MyCoolSite/api/recurso.v2
http://MyCoolSite/api/recurso.v1_1

44. Ejemplos
GET http://MyCoolSite/api/recurso HTTP/1.1
...
api-version: 2
...
http://MyCoolSite/api/v2/recurso
http://MyCoolSite/api/v1.1/recurso
GET http://MyCoolSite/api/recurso HTTP/1.1
...
Accept: application/vnd.company.site.api.resource.v2+json
...

45. Ejemplos
www.facebook.com/v2.7/dialog/oauth
www.facebook.com/v2.7/plugins/
graph.facebook.com/v2.7/

46. Ejemplos
https://api.twitter.com/1.1/statuses/user_timeline.json
https://api.twitter.com/1.1/direct_messages/destroy.json
https://api.twitter.com/1.1/users/report_spam.json

47. Ejemplos
Accept: application/vnd.github.v3+json
Accept: application/vnd.github.loki-preview+json

48. Implementación

54. Version del Controlador por Nombre
public class DummyController : ApiController
{
...
}
public class DummyV2Controller : ApiController
{
...
}
public class V2DummyController : ApiController
{
...
}
public class DummyControllerV2 : ApiController
{
...
}
public class DummyControllerV2 : ApiController
{
// Este controlador no es válido, porque no cumple con la convención de ASP.NET MVC y
// ASP.NET Web API sobre nombres para controladores.
...
}

55. Versión de Controlador por Espacio de Nombres
namespace My.Cool.Api.V1
{
public class DummyController : ApiController
{
...
}
}
namespace My.Cool.Api.V2
{
public class DummyController : ApiController
{
...
}
}

58. Código para los Ejemplos
public class Console
{
public int Id { get; set; }
public string Name { get; set; }
}
public class NexGenConsole : Console
{
public bool IsNexGen { get; set; }
}

59. Código para los Ejemplos
public class ConsoleController : ApiController
{
public virtual IEnumerable<Console> GetConsoles
{
get { return ... }
}
public virtual Console GetConsole(int id)
{
return new Console { Id = id, Name = @"PS3" };
}
}
public class ConsoleV2Controller : ConsoleController
{
public override Console GetConsole(int id)
{
return new NexGenConsole { Id = id, Name = @"PS4", IsNexGen = true };
}
}

60. Código para los Ejemplos
internal static class VersionFinder
{
public static int GetVersionFromRequestData(HttpRequestMessage request) {...}
private static bool NeedsUriVersioning(HttpRequestMessage request, out string version)
{ ... }
private static bool NeedsHeaderVersioning(HttpRequestMessage request, out string version)
{ ... }
private static bool NeedsAcceptVersioning(HttpRequestMessage request, out string version)
{ ... }
private static int VersionToInt(string versionString) { ... }
}

61. Versionado a través de Enrutamiento por Convención

62. Versionado a través de Enrutamiento por Convención

63. Versionado a través de Enrutamiento por Convención

66. Versionado a través de Enrutamiento por Convención

67. Versionado a través de Enrutamiento por Convención

68. Versionado a través de Enrutamiento por Convención

69. Versionado a través de Enrutamiento por Convención

70. Versionado a través de Enrutamiento por Convención
public static class WebApiConfig
{
public static void Register(HttpConfiguration config, IDependencyResolver dependencyResolver)
{
if (config != null)
{
...
config.Services.Replace(typeof(IHttpControllerSelector),
new VersionAwareControllerSelector(config));
...
}
}
}

71. Versionado a través de Enrutamiento por Convención
public static class WebApiConfig
{
public static void Register(HttpConfiguration config, IDependencyResolver dependencyResolver)
{
if (config != null)
{
...
config.Routes.MapHttpRoute(name: @"VersionedApi",
routeTemplate: @"api/v{version}/{controller}/{id}",
defaults: new { id = RouteParameter.Optional },
constraints: new { version = @"[1-9]+[d]*" });
config.Routes.MapHttpRoute(name: @"DefaultApi",
routeTemplate: @"api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional });
...
}
}
}

72. DEMO 1

73. Versionado a través de Enrutamiento por Atributos
…Sino que se

74. Versionado a través de Enrutamiento por Atributos
Uno de los primeros pasos es decorar los controladores
con los atributos de enrutamiento apropiados.
[RoutePrefix(@"api/v1")]
public class ConsoleAttributeController : ApiController
{
[Route(@"consoles")]
public virtual IEnumerable<Console> Console RetrieveConsoles()
{
return ...
}
[Route(@"consoles/{id:int}")]
public virtual Console RetrieveConsole(int id)
{
return new Console { Id = id, Name = @"PS3" };
}
}

75. Versionado a través de Enrutamiento por Atributos
[RoutePrefix(@"api/v2")]
public class ConsoleAttributeV2Controller : ConsoleAttributeController
{
[Route(@"consoles/{id:int}")]
public override Console RetrieveConsole(int id)
{
return new NexGenConsole { Id = id, Name = @"PS4", IsNexGen = true };
}
}
Y ya sólo con esto, se tendría versionado mediante URL,
ya que la declaración de la ruta directamente en el
controlador o la acción, es la naturaleza misma del
enrutamiento por atributo.

76. DEMO 2

77. Versionado a través de Enrutamiento por Atributos
Soportar las modalidades de custom header y custom
media type, simplemente requiere identificar el origen
del dato correspondiente a la versión.

78. Versionado a través de Enrutamiento por Atributos
Sin embargo, es necesario informar a los atributos de
enrutamiento de la existencia de una restricción por
versión, para lo cual:

79. Versionado a través de Enrutamiento por Atributos
internal class VersionConstraint : IHttpRouteConstraint
{
private readonly int allowedVersion;
public VersionConstraint(int version)
{
this.allowedVersion = version;
}
public bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName,
IDictionary<string, object> values, HttpRouteDirection routeDirection)
{
return request == null ?
false :
this.allowedVersion == VersionFinder.GetVersionFromRequestData(request);
}
}

80. Versionado a través de Enrutamiento por Atributos
internal class VersionedRouteAttribute : RouteFactoryAttribute
{
public VersionedRouteAttribute(string template)
: base(template)
{
this.Order = -1;
}
public int Version { get; set; }
public override IDictionary<string, object> Constraints
{
get
{
return new HttpRouteValueDictionary
{
{ string.Empty, new VersionConstraint(this.Version) }
};
}
}
}

81. Versionado a través de Enrutamiento por Atributos
Finalmente, decoramos los controladores con el nuevo
atributo VersionedRouteAttribute.
[RoutePrefix(@"api")]
public class ConsoleAttributeController : ApiController
{
[HttpGet, Route(@“v1/consoles")]
[VersionedRoute(@"consoles", Version = 1)]
public virtual IEnumerable<Console> Console Get()
{
return ...
}
[HttpGet, Route(@“v1/consoles/{id:int}")]
[VersionedRoute(@“consoles/{id:int}", Version = 1)]
public virtual Console Get(int id)
{
return new Console { Id = id, Name = @"PS3" };
}
}

82. Versionado a través de Enrutamiento por Atributos
[RoutePrefix(@"api")]
public class ConsoleAttributeV2Controller : ConsoleAttributeController
{
[HttpGet, Route(@"v2/consoles")]
[VersionedRoute(@"consoles", Version = 2)]
public override IEnumerable<Console> RetrieveConsoles()
{
return base.RetrieveConsoles();
}
[HttpGet, Route(@"v2/consoles/{id:int}")]
[VersionedRoute(@"consoles/{id:int}", Version = 2)]
public override Console Get(int id)
{
return new NexGenConsole { Id = id, Name = @"PS4", IsNexGen = true };
}
}
Y ahora se cuenta con versionado por URL, plus
versionado por custom header y custom media type.

83. DEMO 3

84. RECOMENDACIONES
Y
BUENAS PRÁCTICAS

85. Encontraremos diferentes
posiciones filosóficas sobre la
“manera correcta” de alcanzar
REST, sobre qué es RESTful, y
qué no lo es.
Desafortunadamente, lo
filosófico pasa a lo religioso y
se pierde el foco sobre cuál
debería ser el objetivo real:
construir software que
funcione y un API coherente
que permita consumirle e
integrarle fácilmente.

90. http://shonzilla/api/customers/1234
http://shonzilla/api/v3.0/customers/1234
http://shonzilla/api/v3/customers/1234

91. Literatura y Bibliografía

95. Preguntas

96. ¡GRACIAS!
@rliberoff
https://es.linkedin.com/in/rliberoff
http://www.commitstrip.com/en/2013/08/20/numeros-de-version/