Diseño orientado a recursos

El objetivo de esta Guía de diseño es ayudar a los desarrolladores a diseñar API simples, coherentes y fáciles de usar conectadas en red. Además, ayuda a la convergencia de diseños de API de RPC basadas en socket con API de REST basadas en HTTP.

Por lo general, las API de RPC están diseñadas en términos de interfaces y métodos. Con el tiempo, se agregan cada vez más y el resultado final puede ser una superficie de API confusa y abrumadora debido a que los desarrolladores deben aprender cada método de forma individual. Este proceso es tedioso y propenso a errores.

El estilo arquitectónico de REST se adoptó, en primer lugar, para funcionar bien con HTTP/1.1, pero también para solucionar este problema. Su principio básico es definir recursos nombrados que pueden manipularse con una pequeña cantidad de métodos. Los recursos y métodos se conocen como sustantivos y verbos de las API. Con el protocolo HTTP, los nombres de los recursos se asignan de forma natural a las URL, y los métodos se asignan a los métodos HTTP POST, GET, PUT, PATCH y DELETE. Así, hay muchos menos procesos para aprender, ya que los desarrolladores pueden enfocarse en los recursos y sus relaciones, y suponen que tienen la misma cantidad pequeña de métodos estándar.

En Internet, las API de REST HTTP tienen mucho éxito. En 2010, un 74% de las API de red pública eran API de REST HTTP.

Si bien las API de REST HTTP son muy populares en Internet, la cantidad de tráfico que llevan es más pequeña que las API de RPC tradicionales. Por ejemplo, la mitad del tráfico de Internet en EE.UU. en la hora pico es contenido de video y pocas personas considerarían usar API de REST para entregar tal contenido por razones de rendimiento obvias. Dentro de los centros de datos, muchas empresas usan API de RPC basadas en socket para llevar la mayor parte del tráfico de red, lo que puede incluir pedidos de mayor magnitud de datos (medidos en bytes) que las API de REST públicas.

En realidad, se necesitan las API de RPC y las API de REST HTTP por varias razones. Lo ideal sería que una plataforma de API proporcione la mejor compatibilidad para todos los tipos de API. La Guía de diseño te ayuda a diseñar y compilar API que cumplan con este principio. Lo hace mediante la aplicación de principios de diseño orientados a recursos al diseño general de las API y con la definición de muchos patrones de diseño comunes para mejorar la usabilidad y reducir la complejidad.

NOTA: En esta Guía de diseño, se explica cómo aplicar los principios de REST al diseño de las API de manera independiente del lenguaje de programación, el sistema operativo o el protocolo de red. NO es una guía solo para la creación de API de REST.

¿Qué es una API de REST?

Una API de REST se modela como colecciones de recursos abordables de manera individual (los sustantivos de la API). Se hace referencia a los recursos con sus nombres de recurso y se manipulan mediante un conjunto pequeño de métodos (también conocidos como operaciones o verbos).

Los métodos estándar para las API de REST de Google (también conocidos como métodos REST) son List, Get, Create, Update y Delete. Los métodos personalizados (también llamados operaciones personalizadas o verbos personalizados) están disponibles a los diseñadores de API para las funcionalidades que no se asignan con facilidad a uno de los métodos estándar, como las transacciones de bases de datos.

NOTA: Con “verbos personalizados” no nos referimos a crear verbos HTTP personalizados para la compatibilidad con métodos personalizados. Para las API basadas en HTTP, simplemente se asignan a los verbos HTTP más adecuados.

Flujo de diseño

En la Guía de diseño, se sugiere seguir los pasos a continuación durante el diseño de API orientadas a recursos (se proporcionan más detalles en las secciones específicas más abajo):

  • Determinar los tipos de recursos que proporciona una API
  • Determinar la relación entre recursos
  • Decidir los esquemas de nombres de recurso según los tipos y las relaciones
  • Decidir los esquemas de recursos
  • Adjuntar un conjunto de métodos mínimo a los recursos

Recursos

Por lo general, una API orientada a recursos se modela como una jerarquía de recursos en la que cada nodo es un recurso simple o un recurso de colección. Por conveniencia, se los suele llamar recurso y colección, respectivamente.

  • Una colección contiene una lista de recursos del mismo tipo. Por ejemplo, un usuario tiene una colección de contactos.
  • Un recurso tiene un estado y cero o más subrecursos. Cada subrecurso puede ser siempre o de colección.

Por ejemplo, una API de Gmail tiene una colección de usuarios, cada usuario tiene una colección de mensajes, una de conversaciones, una de etiquetas, un recurso de perfil y muchos recursos de opciones de configuración.

Si bien hay cierta alineación conceptual entre los sistemas de almacenamiento y las API de REST, un servicio con una API orientada a recursos no es necesariamente una base de datos y es muy flexible respecto a su forma de interpretar métodos y recursos. Por ejemplo, con la creación de un evento de calendario (recurso) se pueden crear eventos adicionales para los asistentes, enviar invitaciones por correo electrónico a estos, reservar salas de conferencia y actualizar programas de videoconferencia.

Métodos

La característica clave de una API orientada a recursos es que enfatiza recursos (modelo de datos) por sobre los métodos realizados en los recursos (funcionalidad). Una API orientada a recursos típica expone una gran cantidad de recursos con una pequeña cantidad de métodos. Pueden ser métodos estándar o personalizados. Para esta guía, los métodos estándar son: List, Get, Create, Update y Delete.

Si la funcionalidad de la API se asigna de forma natural a uno de los métodos estándar, ese método debería usarse en el diseño de la API. En los casos en que la funcionalidad no se asigna de forma natural a uno de los métodos estándar, pueden usarse métodos personalizados. Los métodos personalizados ofrecen la misma libertad de diseño que las API de RPC tradicionales, que pueden usarse para implementar patrones de programación comunes, como las transacciones de bases de datos o el análisis de datos.

Ejemplos

Las siguientes secciones presentan algunos ejemplos reales de cómo aplicar el diseño de una API orientada a recursos en servicios a gran escala. Puedes encontrar más ejemplos en el repositorio de API de Google.

API de Gmail

El servicio de la API de Gmail implementa la API de Gmail y expone la mayor parte de la funcionalidad de Gmail. Tiene el siguiente modelo de recursos:

  • Servicio de API: gmail.googleapis.com
    • Una colección de usuarios: users/*. Cada usuario tiene los recursos que se detallan a continuación.
      • Una colección de mensajes: users/*/messages/*
      • Una colección de conversaciones: users/*/threads/*
      • Una colección de etiquetas: users/*/labels/*
      • Una colección de historial de cambios: users/*/history/*
      • Un recurso que representa el perfil del usuario: users/*/profile
      • Un recurso que representa las opciones de configuración del usuario: users/*/settings

API de Cloud Pub/Sub

El servicio pubsub.googleapis.com implementa la API de Cloud Pub/Sub, que define el siguiente modelo de recursos:

  • Servicio de API: pubsub.googleapis.com
    • Una colección de temas: projects/*/topics/*
    • Una colección de suscripciones: projects/*/subscriptions/*

NOTA: Puede que otras implementaciones de la API de Pub/Sub elijan esquemas de denominación de recursos distintos.

API de Cloud Spanner

El servicio spanner.googleapis.com implementa la API de Cloud Spanner, que define el siguiente modelo de recursos:

  • Servicio de API: spanner.googleapis.com
    • Una colección de instancias: projects/\*/instances/\*
      • Una colección de operaciones de instancias: projects/*/instances/*/operations/*
      • Una colección de bases de datos: projects/*/instances/*/databases/*
      • Una colección de operaciones de bases de datos: projects/*/instances/*/databases/*/operations/*
      • Una colección de sesiones de bases de datos: projects/*/instances/*/databases/*/sessions/*
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...