Lo que hay que tener en cuenta antes de escribir la Guía de Diseño de la API

por / martes, 29 mayo 2018 / Publicado enBlog
UST Global es partner patrocinador de Alfresco Day Madrid 2018
keensoft UST Global en el evento final de Technovation Challenge

En los últimos años, la concepción de las APIs como productos, ha impulsado el mercado de venta o exposición de servicios en Internet. La utilización de una estrategia ganadora, como la descripción mediante OpenApis y la gestión con apigee, está proporcionando a muchas compañías una adopción rápida y segura de este enfoque. Sin embargo, antes de abordar la parte operativa, es necesario recopilar un conjunto de guías para describir cómo funciona una API REST en concreto. Este documento permitirá guiar a desarrolladores de ambos bandos (productores y consumidores), ya que está enfocado en la definición de todas las reglas de interacción.

Asimismo, cuando se construyen aplicaciones Cloud Native, un enfoque API First es obligado. API First significa que todo lo que se hace debe hacerse con la idea de que lo que se está construyendo es una API que será consumida por aplicaciones y servicios desde móviles y cosas. Como ya estableció Adobe, los tres pilares básicos del API First Design son:

  • La API es el interfaz de usuario primario de tu aplicación
  • La API es lo primero, antes de la implementación
  • La API es descriptiva (e incluso mejor si es auto-descriptiva)

Por estos motivos, escribir una Guía de Diseño para una API es el primer paso para asegurar un catálogo de servicios coherente.

Muchas grandes compañías han compartido su Guía de Diseño para APIs públicas:

Algunas de las interacciones requeridas por las API pueden se resueltas de modos diferentes, como podrá apreciarse en la lista anterior. Sin embargo, otra gran parte de las guías pueden ser extraídas directamente de estándares internacionales y de estándares de Internet.

Definición de la Guía

Para la semántica, el formato y el nombrado se utilizan las convenciones descritas en RFC 2119 – Key words for use in RFCs to Indicate Requirement Levels

Protocolo HTTP

Las URIs deben cumplir la especificación RFC 3986 – Uniform Resource Identifier (URI): Generic Syntax, incluyendo componentes estándar: scheme, authority, path, query y fragment.

Las plantillas de URI, que incluyen campos variables, deben ser expresadas de acuerdo a RFC 6570 – URI Template {variable}

Las cabeceras HTTP deben ser definidas o referenciadas según RFC 7231 – Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, que incluye Accept, Accept-Charset, Content-Language, Content-Type, Link y Location (aunque a veces son reemplazadas por enfoques HATEOAS) y Prefer.

Las cabeceras de aviso, habitualmente utilizadas para informar sobre una API deprecada, deben seguir RFC 7234 – Hypertext Transfer Protocol (HTTP/1.1): Caching

RFC 6585 – Additional HTTP Status Codes introduce nuevos códigos de estado, como el “429 Too Many Requests”. En la mayoría de APIs, para prevenir abusos, se añade un límite al número de peticiones, por lo que este nuevo código encaja a la perfección.

Para actualizar un recurso de manera incremental, se utiliza el verbo PATCH descrito en RFC 5789 – PATCH Method for HTTP.

Payload en JSON

A pesar de que el payload en las APIs REST puede ser enviado utilizando diferentes formatos, JSON se ha convertido en el estándar de facto.

La representación de los datos en JSON debe adecuarse a RFC 7159 – The JavaScript Object Notation (JSON) Data Interchange Format.

Cuando se utilizan enlaces dentro del payload JSON, existen dos alternativas:

Los tipos básicos de JSON son String, Number, Object, Arrays, Boolean y Null. Para definir Date y Time, los formatos deben acomodarse a la especificación RFC 3339 – Date and Time on the Internet: Timestamps (ISO 8601)

Las unidades y medidas de internacionalización se incluyen de acuerdo a diferentes estándares:

Autenticación

Las APIs REST no tienen estado, por lo que la autenticación no debe depender de cookies o sesiones. Cada petición debe venir acompañada de credenciales de autenticación.

Si HTML Basic Authentication es suficiente en términos de seguridad, debe ser empleado de acuerdo a RFC-7617 – The ‘Basic’ HTTP Authentication Scheme.

Sin embargo, la mayoría de plataformas de servicios utilizan una api key como token de credenciales. Esta api key puede ser gestionada internamente por el servicio, pero cuando se utiliza un protocolo estándar como OAuth 2.0, deben tenerse en cuenta las siguientes normas:

Otros temas

CORS (Cross-Origin Resource Sharing) debe ser soportada, atendiendo las cabeceras de petición Origin y Access-Control-Request-Method.

Las APIs deben soportar versionado explícito (bien en URL o en cabecera), utilizando el estándar de facto Semantic Versioning 2.0.0

Consideraciones finales

No existe un estándar para el diseño de APIs, ya que no puede especificarse uno que sirva para todos los casos. Por este motivo, antes de comenzar el proceso de publicación y exposición del modelo de datos de consumo, deben tomarse algunas decisiones: formatos aceptados, esquemas de autenticación o políticas de obsolescencia son algunos ejemplos. En cualquier caso, aunque la redacción de una Guía de Diseño de la API es una cuestión de elecciones, muchas de las preguntas pueden ser directamente respondidas mediante la adopción de estándares.

Encuentra el tiempo necesario para escribir una guía de relación para consumidores y productores de tus APIs. ¡Seguro que lo agradeces en el futuro!

Responsable tecnológico para soluciones de gestión documental en keensoft. Especialista en Alfresco y en implantaciones de Administración Electrónica.

Etiquetado bajo:

Deja un comentario

SUBIR