Tipos de APIs: Request - Response

Tipos de APIs: Request - Response

Cuando comienzo un nuevo proyecto siempre invierto tiempo en pensar qué tipo de API necesito ahora y en el futuro, a corto y medio plazo. ¿Por qué hago esto? ¿Por qué no creo una API Rest y ya está? Como explicaré a continuación hay vida más allá de las API Rest y esos otros tipos de APIs existen porque las API Rest no sirven para todo. Volviendo al tema, invierto este tiempo porque que si tomo esta decisión a la ligera, creo la API y ya hay algún servicio utilizándola, es muy difícil, por no decir imposible, cambiarla. Para ahorrarte dolores de cabeza, voy a explicarte los tipos de APIs que existen, sus puntos fuertes y puntos débiles y algunos ejemplos de cada tipo. Esto te ayudará a diseñar una API que te permita hacer los cambios que necesites en el futuro.

API Request - Response

Esta API es la más típica. Expone un interfaz a través de un servidor HTTP. La API tiene un conjunto de endpoints. Los clientes hacen peticiones(requests) a esos endpoints y el servidor contesta con respuestas(responses). Normalmente la respuesta es un JSON(más usada) o XML. Hay 3 formas de implementar este tipo de APIs, REST, RPC y GraphQL.

REST o Representational State Transfer

Es la forma más popular de implementar una API. Todas las grandes compañías exponen APIs con esta implementación: Google, Stripe, Twitter o GitHub. Las APIs REST exponen sus datos a traves de recursos(resources) y a través de métodos estándar HTTP que representan la creación(create), lectura(read), actualización(update) y borrado(delete) sobre estos recursos. Más conocicod por su acrónimo CRUD.

A continuación algunas reglas de las APIs REST:

  • La URL(https://api.dominio.com) junto con el recurso(/usuarios) conforma el endpoint con el que se interactúa: https://api.dominio.com/usuarios
  • Algunos recursos, implementan 2 URLs. Una para devolver toda la colección de elementos(/usuarios) y otra para devolver un elemento dentro de la colección(/usuarios/:id -> /usuarios/123)
  • Se utilizan nombres en plural (/users) y no verbos(/getUsers)
  • Los métodos HTTP como GET, POST, UPDATE y DELETE le dicen al servidor qué acción debe realizar. Se pueden ejecutar diferentes métodos sobre el mismo recurso:

CREATE /usuarios: creará un nuevo usuario

READ /usuarios: devolverá la lista de todos los usuarios

UPDATE /usuarios/123: actualiza el usuario 123

DELETE /usuarios/123: borra el usuario 123

  • El servidor devuelve respuestas estándar HTTP indicando el resultado de la operación sobre la API. Por ejemplo, si todo ha ido bien se devolverá un 2xx, si ha habido algún error en el servidor un 5xx. Aquí una lista de los errores estándar.
  • Como ya dije antes, las APIs REST devuelven JSON o XML. JSON se ha convertido en el estándar.
Operación Verbo HTTP URL: /usuarios URL: /usuarios/123
Crear POST Crear un nuevo usuario -
Leer usuario 123 GET Listar TODOS los usuarios Listar el usuario 123
Modificar usuario 123 PUT o PATCH Modificar TODOS los usuarios Modificar el usuario 123
Borrar usuario 123 DELETE Borrar TODOS los usuarios Borrar el usuario 123

¿Cómo acceder a datos relacionados con otros?

Imagina que quieres obtener todos los documentos de un usuario. En ese caso tendrías que acceder primero al usuario, identificado por su id, y después a sus documentos.

GET https://api.dominio.com/users/123/documentos

RPC o Remote Procedure Call

RPC es uno de los tipos de APIs más simples. En RPC el cliente ejecuta un bloque de código en el servidor. REST se basa en recursos y RPC en acciones. El funcionamiento es el siguiente: el cliente envía un método y unos argumentos al servidor, y recibe como respuesta un JSON o XML.

Este tipo de APIs siguen 2 reglas:

  • Los endpoints contienen el nombre de la operación que se ejecutará.
  • Las llamadas a la API se hacen con el verbo HTTP que más se adapte a la situación: GET para solo-lectura y POST para todo lo demás.

RPC funciona bien para APIs que exponen acciones que no pueden ser adaptadas al modelo CRUD. Por ejemplo, una API sobre la que se pueden hacer acciones como bloquear, liberar, marcar, etiquetar, liberar ... como puedes ver son difíciles de adaptar al modelo CRUD.

Las APIs RPC no utilizan únicamente HTTP, existen otros tips de APIs RPC como Apache Thrift o gRPC.

GraphQL

GraphQL no es un tipo de API, si no un lenguage para APIs, de ahí la terminación en QL(Query Language). Fue desarrollada por Facebook y liberada en 2015. Está ganando mucha popularidad y muchas de las grandes compañías ofrecen, además de la versión REST de su API, también la versión GraphQL.

GitHub ofrece su API tanto en modo REST como en modo GraphQL
GitHub ofrece su API tanto en modo REST como modo GraphQL

GraphQL sólo necesita un único endpoint y no utiliza verbos HTTP. Lo único que GraphQL necesita es indicarle en el cuerpo del JSON si quieres hacer una query(leer datos) o una mutación(crear o modificar datos existentes).

¿Qué ventajas tiene GraphQL sobre REST o RPC?

  • Disminuye el número de peticiones necesarias, lo que se traduce en más velocidad

GraphQL permite con sólo una petición recibir lo que necesitamos. Él se encarga internamente de realizar las operaciones que necesite pero en la parte del servidor.

  • Evita el versionado

GraphQL permite añadir nuevos campos sin tener que versionar la API y sin afectar a las queries existentes. Igualmente es muy fácil borrar campos no necesarios examinando los logs de uso de esos campos y borrándolos en el momento que nadie los esté utilizando.

  • Payload más pequeño

El payload es el conjunto de datos que recibimos como respuesta de la API. En REST y RPC recibimos, por defecto, todos los datos de ese recurso. Es cierto que se pueden filtrar los datos que necesitamos, pero su implementación no es trivial. GraphQL obliga a especificar en la petición qué datos se deben devolver.

  • Fuertemente tipado

En tiempo de desarrollo, GraphQL comprueba que una query es correcta sintácticamente y válida. Esto permite construir clientes de buena calidad y con menos errores.

  • Introspección

Existen herramientas como Swagger que ayudan a que una API REST sea fácilmente explorable. GraphQL lo hace por defecto sin necesidad de herramientas externas, ya que a través de nuestro navegador podremos acceder a una URL del tipo https://api.dominio.com/___graphql que nos mostrará el explorador de GraphQL llamado GraphiQL.

GraphiQL

Pero GraphQL también tiene sus inconvenientes. El más grande es la complejidad que agrega al proveedor y con ello la carga de procesamiento que añade al servidor. Además optimizar el renimiento de las queries es complejo, sobre todo si recibes queries de fuera de tu organización y que no puedes controlar.

REST RPC GraphQL
Qué? Expone datos como recursos y usa métodos estándar HTTP para reperesentar las operaciones CRUD. Expone métodos basados en acciones. Los clientes envían el nombre del método y los argumentos. Lenguaje para hacer consultas. Los clientes definen la estructura de la respuesta.
Quién? Twitter, Stripe, GitHub, Google Slack, Flickr GitHub, Yelp, Facebook
Cómo? GET /usuarios/:id GET /usuarios.get?id=:id query ($id:String!) { usuario (login: $id) { nombre telefono email } }
Verbos HTTP GET, POST, PUT, PATCH, DELETE GET, POST GET, POST
Pros
  • Nombres de métodos estándar
  • Formato de argumentos estándar
  • Códigos de estado estándar
  • Utiliza la potencia de HTTP
  • Fácil de mantener
  • Fácil de entender
  • Payloads pequeños
  • Rendimiento alto
  • Evita múltiples peticiones
  • Evita versionado
  • Payloads pequeños
  • Fuertemente tipado
  • Herramienta de exploración incluida
Contras
  • Payloads grandes
  • Múltiples peticiones
  • Difícil de utilizar
  • No hay estándares definidos
  • Aumento exponencial de las funciones
  • Requiere procesado extra de las consultas
  • Difícil optimizar el rendimiento del backend
  • Demasiado complejo para APIs simples
Cuándo? Para APIs que hacen operaciones tipo CRUD Para APIs que exponen muchas acciones Cuando se necesitan consultas flexibles y un mantenimiento consistente