Consumiendo API REST para principiantes (apto para novatos)

Como desarrollador que usa IRIS como base de datos en un par de proyectos, uso APIs REST todo el tiempo. En mi opinión, saber cómo consumir un recurso de una API REST es crucial para poder utilizar APIs REST externas con %Net.HttpRequest, porque permite la integración con aplicaciones y servicios web modernos, y es una habilidad esencial para un desarrollador backend que ama y utiliza IRIS como base de datos.

¿Qué es y para quién sirve %Net.HttpRequest?

Es solo una clase, pero es la forma adecuada de hacer solicitudes fuera del framework. Es una clase sencilla que proporciona métodos HTTP como GET, POST y PUT, además de otros métodos de solicitud, os permite “jugar” con los encabezados, crear la solicitud como queráis y gestionar la respuesta que recibáis. Por cada solicitud enviada usando %Net.HttpRequest, recibimos un objeto %Net.HttpResponse que contiene la respuesta con el mismo patrón.

Una forma adecuada de manejar solicitudes a APIs REST con %Net implica comprobar tanto el valor devuelto por %Status como los códigos de estado de la respuesta, lo cual os permite generar mensajes de error específicos y filtrar las respuestas cuando la solicitud falla. La forma recomendada es usar macros como $$$ISER() o $SYSTEM.Status.IsOK(). También podemos usar $SYSTEM.Status.DisplayError() para inspeccionar el código de estado HTTP y gestionarlo.

Antes de empezar a ensuciarnos las manos, debemos saber quién es JSONPlaceholder, así que en el sitio oficial dicen:

"API falsa, gratuita y fiable para pruebas y prototipos"

Y eso es exactamente lo que es: una API REST gratuita en línea para experimentar. Son datos falsos, incluso podemos enviar datos con POST, pero esta guía trata únicamente de consumir datos, así que centrémonos en eso. Y este es un ejemplo sencillo de cómo consumir un JSON desde un servicio REST API.

Set request = ##class(%Net.HttpRequest).%New()
Set request.Server = "jsonplaceholder.typicode.com"
Set status = request.Get("/posts/1")

If $$$ISERR(status) {
    Do $SYSTEM.Status.DisplayError(status)
    Quit
}

Set response = request.HttpResponse
Set httpStatus = response.StatusCode
Set body = response.Data.Read()

If httpStatus < 200 || httpStatus >= 300 {
    Write "HTTP Error: ", response.StatusLine, !
    Quit
}

Write "HTTP Status: ", response.StatusLine, !
// Do what ever you want with it!

¿Qué hacemos?

1. Asignar “request” a una nueva instancia del objeto %New.HttpRequest.
2. Asignar una ubicación/dirección a la propiedad Server en la instancia de request.
3. Hacer una solicitud GET al endpoint que proporcionamos a la función “/posts/1”, lo que significa que pedimos datos de “posts” con id igual a 1 (para obtener solo el primer mensaje; podemos especificar solo “posts” y obtenerlos todos; es bueno trastear con ello).
4. Comprobar si hay algún error en la función usando $$$ISERR con el estado devuelto por el método GET de la solicitud. Si no lo hay, la solicitud se envió correctamente desde nuestro endpoint.
5. Asignar la variable response desde el propio objeto request.
6. Extraer el código de estado y el cuerpo.
7. Comprobar si el código de respuesta es OK. Si el código devuelto es mayor que 200 y menor o igual que 300, está OK (307 es una redirección, así que no es lo que necesitamos aquí).

Entonces, en perspectiva general, ¿qué estamos haciendo aquí?

1. Crear una solicitud predefinida usando la clase
2. Intentar consumir los datos que necesitamos
3. Gestionar los casos tanto de error como de éxito

Si todo va bien, deberíais obtener algo así como un objeto JSON:

Y así es como consumimos datos de una API REST, pero ¿qué podemos hacer con ello?
Veamos cómo extraer los datos de la respuesta:

Set reponseBodyAsJSON = {}.%FromJSON(body)

Write "id: ", reponseBodyAsJSON.id, !
Write "title: ", reponseBodyAsJSON.title, !
Write "body: ", reponseBodyAsJSON.body, !

De esta manera, dividimos la respuesta en pares clave-valor como debe ser un JSON.
Así es como podemos acceder y consumir fácilmente un recurso de una API REST usando el método GET y la clase %Net.HttpRequest. Esta es una guía realmente apta para principiantes que os permite tener una “visión general” de cómo lo hacemos.

Aprender la magia de las APIs REST es vuestro deber.

Como este tema es muy accesible, podéis experimentar fácilmente haciendo solicitudes y probando diferentes métodos. En la próxima guía veremos cómo transferir datos de forma segura entre dos servicios basados en REST.