Versiones de una API

7

Estoy comenzando un proyecto paralelo, la primera etapa será construir una aplicación web con MVC, en etapas posteriores agregaremos clientes para plataformas móviles. Mi idea fue crear una API que todas las aplicaciones (web y móvil) pasen para obtener / guardar datos.

Debido a que estas diferentes plataformas estarán en diferentes ciclos de lanzamiento, necesitaré una forma para, por ejemplo, iPhone, trabajar con una versión de la API mientras el sitio web está utilizando una versión actualizada. ¿Cuál es la mejor manera de hacerlo?

Mis ideas hasta ahora son:

  • Cree un proyecto separado para hospedar la API web de MVC y hospede eso en un subdominio o en una subcarpeta del sitio raíz. Luego, haga referencia directamente a la DLL o haga referencia a ella a través de la web (parece una llamada http innecesaria)
  • Aloja la API dentro del proyecto MVC que será el sitio web e intenta la versión basada en url allí. Hice algunas pruebas rápidas con eso esta mañana y no pude hacerlo funcionar, siempre residió en \ api (no pude hacerlo en \ api_v2)
pregunta Jeremy Hutchinson 01.05.2013 - 22:41

3 respuestas

9

En un gran servicio con múltiples consumidores y servicios integrados, aquí hay algunos principios y pautas que seguimos para RESTARnos en nuestra API web. Si no estás tratando de ser RESTful, etc ... y solo quieres una API simple de http, es posible que no se aplique.

Principios clave:

  • Un recurso se identifica mediante una URL RESTful (site.com/api/user/6).
  • Esa URL debe ser un enlace permanente (siempre se refiere a ese recurso). Los servicios externos y los consumidores de la API pueden persistir ese enlace permanente
  • Las diferentes versiones del cliente pueden solicitar site.com/api/user/6 y, dependiendo de la versión, pueden obtener una representación diferente (versión) del recurso.
  • Nos esforzamos por hacerlo bien, revisamos las API, etc ... pero nos damos cuenta de que no lo haremos a veces y deseamos la posibilidad de poder versionarlo y hacerlo bien.

Consideramos poner la versión en la URL, pero eso rompe los principios RESTful clave.

enlace

Buena lectura en el diseño y control de versiones de la API web

Lo que hicimos (básicamente, agitando las manos sobre los detalles):

  • Coloque la versión de la solicitud en el encabezado de tipo aceptar / contenido utilizando las propiedades de tipo MIME: application / json; versión = 2 (consideramos los tipos MIME del proveedor que BTW, usos de github ). También admitimos pasar la cadena de consulta para los escenarios de mashup web.
  • Hemos personalizado el enrutamiento para que la solicitud de la versión 2 de la solicitud de recursos se dirija al (Recurso) 2Controller.
  • En una solicitud de OPCIONES http, el servidor iteraría sobre las rutas y expondría los recursos, las plantillas de ruta disponibles y la versión mín / máx (nuestro atributo personalizado puesto en el controlador / clases).
  • El cliente sabe qué versión es, de modo que lo primero que hizo el cliente es una solicitud de OPCIONES y negoció la versión máxima que el cliente y el servidor entienden, luego la enviará en el encabezado.
  • Dado que el servidor tiene varios controladores, es capaz de devolver versiones diferentes de ese recurso.
  • A pesar de que somos capaces de versionar el recurso, nos abstenemos de adoptar un enfoque puramente aditivo si es posible (los clientes más antiguos ignoran las propiedades adicionales de la deserialización). iOS lo hará bien, ya que solo son datos adicionales en los diccionarios.
  • Uno de los beneficios que obtuvimos de las OPCIONES al exponer rutas, fue que en realidad evitamos las matemáticas de ruta en el cliente. Sabe qué versión es: el cliente http se transfiere a un diccionario y las direcciones URL se formatean utilizando las rutas anunciadas por el servidor.

Estoy considerando la posibilidad de escribir un blog y compartir cómo nos integramos en la API web para versionar nuestros recursos. Si lo hago, haré un seguimiento aquí con un enlace.

    
respondido por el bryanmac 02.05.2013 - 02:57
1

Su API no debería preocuparse por quién / qué la consume. La API proporciona un contrato y lo cumple. Depende del consumidor saber qué hacer con el resultado. No veo por qué su iPhone y su aplicación web necesitarían un contrato diferente.

    
respondido por el Jean-Bernard Pellerin 01.05.2013 - 22:44
1

Estoy de acuerdo con lo que dijo Jean-Bernard. Debes tener una API para que todos puedan acceder a ella.

Pero dicho eso, eventualmente tendrás más de una versión. Usted manejaría eso en diferentes sucursales en su sistema de control de fuente. Si alguna vez necesita tener más de una versión publicada, recomiendo usar subdominios:

respondido por el amhed 02.05.2013 - 01:23

Lea otras preguntas en las etiquetas