Textual description of firstImageUrl

Diseño de una API REST

Tan pronto se empieza a trabajar en el desarrollo de una API, el primer problema que aparece en el camino es el del buen diseño. Un diseño robusto es la característica clave para una buena API. Una API mal diseñada puede llevar a un mal uso de esta, o lo que es peor aun, el no uso de ella por parte de los programadores, quienes son al final del día los usuarios a quienes está dirigida. 

Hay dos aspectos que son clave para tener en cuenta al diseñar una API exitosa y son los siguientes:

  • Los principios descritos en la literatura acerca de las API RESTful. Por ejemplo, tenemos Roy Fielding, Leonard Richardson, Martin Fowler, la especificación HTTP.
  • Las actuales prácticas de los Gigantes de la Web. Es decir, qué están haciendo las grandes compañías en esta materia. Cómo están planteando la arquitectura de sus APIs.

Hoy en día se puede distinguir que existen dos corrientes de trabajo como son: en primer lugar, el purismo, que es seguir los principios REST sin ninguna desviación, o el pragmatismo, que es un enfoque mas práctico de proveer a los clientes una API más utilizable. No obstante, se puede pensar que en el medio de los dos se encuentra un enfoque mejor y más prudente.

Cada día surgen nuevos interrogantes y obstáculos por superar cuando se trabaja en las REST APIs y no hay una respuesta perfecta para todos ellos. Esto es porque los principios básicos aun son materia de discusión y en cuanto a las mejores prácticas, pues también existe sobre esto un gran debate y en el mejor de los casos, como producto de este debate, se consolidará un buen conjunto de ellas. 

Conceptos principales

 

Simplicidad

Uno de los objetivos de las API es que sean utilizadas. De manera que la estrategia de diseño de la API debe apuntar principalmente a alcanzar la mayor cantidad de programadores posible, abriendo así el sistema a Internet. Es por lo tanto crucial que la API sea auto-descriptiva y tan simple como se pueda, de modo que los desarrolladores no necesiten acudir a la documentación. Esta condición se conoce como affordance: la API sugiere su propio uso.

Cuando se diseña una API, los siguientes principios deberían tenerse en cuenta:
  • La semántica de la API debe ser intuitiva. URI, parámetros, request, response: un desarrollador debería poder usarlos sin tener que ir a la documentación de la API.
    • Los términos deben ser comunes y concretos, en lugar de emanar del lenguaje funcional o técnico. Por ejemplo: Clientes, Ordenes, Direcciones, Productos.
    • No debería haber diferentes formas de realizar la misma acción
  • La API está diseñada para sus clientes, los desarrolladores, y no debería ser simplemente una capa de acceso sobre el modelo del dominio. La API debe proveer funciones simples que se ajusten a las necesidades de los desarrolladores. Un error común es basar el diseño de una API en un modelo de datos existente, lo cual generalmente es muy complejo.
  • En la fase inicial de diseño, se debe enfocar en los principales casos de uso y dejar los casos excepcionales para fases posteriores. 

Ejemplos cURL


Mostrar ejemplos utilizando el comando cURL es bastante común para ilustrar las llamadas a la API: los gigantes de la web lo hacen, así como se ve en la literatura general.

Veamos algunos caso de documentación de las APIs utilizando ejemplos cURL:
Se recomienda siempre ilustrar la documentacion de la API con ejemplos cURL. Los lectores simplemente pueden copiar y pegar, y luego remover cualquier ambiguedad en los detalles de la llamada. 

CURL –X POST \ -H "Accept: application/json" \ -d '{"state":"running"}' \ https://api.sandbox.paypal.com/v1/oauth2/token


Granularidad Promedio

La teoría de que "Un recurso = Una URL" tiende a incrementar el número de recursos. Es importante mantener un límite razonable. 
Por ejemplo: una persona contiene una dirección la cual, a su vez, contiene un país. Es importante evitar hacer 3 llamadas a la API:

CURL https://api.fakecompany.com/v1/users/1234
< 200 OK
< {"id":"1234", "name":"Antoine Jaby", "address":"https://api.fakecompany.com/v1/addresses/4567"}
CURL https://api.fakecompany.com/addresses/4567
< 200 OK
< {"id":"4567", "street":"sunset bd", "country": "http://api.fakecompany.com/v1/countries/98"}
CURL https://api.fakecompany.com/v1/countries/98
< 200 OK
< {"id":"98", "name":"France"}

Especialmente porque estas tres piezas de información son comúnmente utilizadas juntas. Esto podría desencadenar en problemas de desempeño.  Pero por otra parte, acumular demasiada información a priori puede provocar que las llamadas a la API y la comunicación sean muy pesadas.

Diseñar una API con una óptima granularidad no es sencillo. Esto es usualmente cultural y fruto de pasadas experiencias de diseño de APIs. En general, se debe evitar que los intercambios sean demasiado grandes o demasiado específicos.

En la práctica se recomienda:
  • Sólo agrupar recursos que son casi siempre accesados juntos
  • No incluir colecciones que tengan muchos componentes. Por ejemplo, una lista de trabajos actuales es limitada (es difícil tener más de dos o tres trabajos al tiempo) pero una lista de trabajos pasados es mucho más larga.
  • Tener un máximo de dos niveles de objetos anidados (por ejemplo, /v1/users/addresses/countries)

Nombres de Dominio de APIs 

En términos de nomnres de dominio, todos los gigantes de la web no tienen las mismas prácticas. Algunos de ellos como Dropbox, utilizan varios dominios o subdominios para sus APIs.
Para normalizar nombres de dominio teniendo en cuenta el affordance, se recomienda usar sólo 3 subdominios para su ambiente de producción:

Esta subdivisión permite que el desarrollador intuitivamente pueda:
  • Consumir efectivamente la API
  • Obtener un token oauth2 para consumir la API
  • Acceder al portal de desarrollador de la API
Algunos gigantes de la web, como Paypal, también proveen un ambiente sandbox (de pruebas), el cual es muy util para probar la API antes de usarla en vivo en el ambiente de producción. 
 Se recomienda usar dos subdominios para su ambiente sandbox (de pruebas)
  
Seguridad

Dos protocolos se usan para la seguridad de REST APIs:

Se recomienda utilizar OAuth2 para asegurar la API
  •  A diferencia de OAuth1, OAuth2 permite administrar la autenticación y autorización de recursos para cualquier tipo de aplicación (app para móvil nativa, app para tablet nativa, app de Javascript, app web de servidor, procesamiento en lotes,  etc) con o sin el consentimiento del propietario del recurso.
  • OAuth2 es el estándar de facto para seguridad de APIs. Usar otra tecnología afectaría el desarrollo y la adopción de su API.
  • Finalmente, la seguridad de recursos es un área compleja , una solución hecha en casa se convertiría seguramente en una brecha de seguridad. 

Con respecto a la validación de tokens OAuth2 se recomienda la solución de Google, flujo implícito de permiso

Recomendamos usar siempre https para comunicarse con proveedores OAuth2 y proveedores API.

Para validar su implementación de OAuth2 recomendamos la siguiente prueba:
  1. Desarrollar un cliente consumiendo su implementación OAuth2 y hacer una llamada a su API
  2. Luego reemplazar los nombres de dominio de su API por los nombres de domino de Google
  3. Si funciona, la implementacion fue exitosa.

Fuentes


  • How to design a REST API - https://blog.octo.com/en/design-a-rest-api/  
  • REST Discussion draft - https://www.w3.org/2001/sw/wiki/REST
on
Labels: , , , , , ,

No hay comentarios.:

Publicar un comentario

Suscribirse a: Comentarios de la entrada (Atom)