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. Al mismo tiempo, también ayuda a la convergencia de los diseños de las API de RPC basadas en sockets con las 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 los métodos se conocen como los sustantivos y los verbos de las API. Con el protocolo HTTP, los nombres de los recursos se mapean de forma natural a las URL, mientras que los métodos lo hacen 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 han tenido mucho éxito. En 2010, alrededor del 74% de las API de red pública eran API de REST de HTTP (o similares a REST), la mayoría usaba JSON como el formato de conexión.
Si bien las API de HTTP/JSON 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 HTTP/JSON 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 HTTP/JSON públicas.
En realidad, se necesitan las API de RPC y las API de HTTP/JSON 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.
¿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).
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.
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.
En estos ejemplos, el asterisco indica un recurso específico de la lista.
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 subprocesos:
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 la configuración del usuario:
users/*/settings.
- Una colección de mensajes:
- Una colección de usuarios:
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/*.
- Una colección de temas:
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/*. Cada instancia tiene los siguientes recursos. - Una colección de operaciones:
projects/*/instances/*/operations/*. - Una colección de bases de datos:
projects/*/instances/*/databases/*. Cada base de datos tiene los siguientes recursos.- Una colección de operaciones:
projects/*/instances/*/databases/*/operations/*. - Una colección de sesiones:
projects/*/instances/*/databases/*/sessions/*.
- Una colección de operaciones:
- Una colección de instancias: