Consumindo REST-APIs para Leigos (Amigável para Iniciantes)

Como um desenvolvedor que usa Cache como DB (Banco de Dados) em alguns projetos, estou usando REST APIs o tempo todo. Por isso, saber como consumir um recurso de uma REST API é, na minha opinião, crucial. É essencial saber como consumir APIs REST externas usando %Net.HttpRequest porque isso permite a integração com aplicações e serviços web modernos e é uma habilidade crucial para um desenvolvedor backend que gosta e usa Cache como DB.

O que é e quem é %Net.HttpRequest?

É simplesmente uma classe, mas esta é a forma adequada de fazer requisições para fora do framework. É uma classe simples que fornece métodos HTTP como GET, POST, PUT e todos os outros métodos de requisição. Ela permite que você "brinque" com os cabeçalhos (headers) e construa a requisição como desejar, e também ensina como manipular a resposta que você recebe.

Para cada requisição enviada usando %Net.HttpRequest, recebemos em troca um objeto %Net.HttpResponse que contém a resposta no mesmo padrão.

Uma forma adequada de lidar com requisições de REST API envolvendo %Net é verificar tanto o valor de %Status retornado quanto os códigos de status da resposta. Isso permite que você levante mensagens de erro específicas e filtre as respostas para entender por que a requisição falhou, se necessário. A forma recomendada é usar macros como $$$ISERR() ou $SYSTEM.Status.IsOK(). Podemos usar $SYSTEM.Status.DisplayError() para inspecionar o código de status HTTP para o tratamento de erros.

Antes de colocarmos a mão na massa, devemos saber quem é JSONPlaceHolder. No site oficial eles dizem:

"API fake, gratuita e confiável para testes e prototipagem."

E é exatamente isso que é. É uma API REST online gratuita para brincar, os dados são fakes e podemos até mesmo enviar dados (POST) para ela. Mas este guia é sobre consumir dados, então vamos focar nisso.

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!

O que fizemos?

1. Atribuímos a variável request a uma nova instância do objeto %Net.HttpRequest.
2. Atribuímos um local/endereço à propriedade Server na instância request.
3. Fazemos uma requisição GET para o endpoint que fornecemos à função: /posts/1. Isso significa que estamos solicitando dados da seção "posts" com id igual a 1 (para obter apenas a primeira mensagem. Podemos especificar apenas "posts" e obter todos eles; é bom brincar com isso).
4. Verificamos se houve algum erro na função usando $$$ISERR com o status retornado pelo método GET. Se não houver erro, a requisição foi enviada com sucesso do nosso endpoint.
5. Atribuímos a variável response do próprio objeto request.
6. Extraímos o status e o corpo.
7. Verificamos se o código de resposta é OK. Se o código retornado for maior ou igual a 200 e menor que 300, está OK (307 é redirecionamento, o que é menos o que precisamos aqui).

De uma perspectiva geral, o que estamos fazendo aqui?

1. Construindo uma requisição predefinida usando a classe.
2. Tentando consumir os dados de que precisamos.
3. Manipulando os cenários de falha e sucesso.

Se tudo correr bem, você deverá receber um objeto JSON como este:

E é assim que consumimos dados de uma REST API!

O que podemos fazer com a resposta?

Vamos ver como extrair os dados da resposta:

Set reponseBodyAsJSON = {}.%FromJSON(body)

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

Desta forma, quebramos a resposta em pares chave-valor, como um JSON deve ser.

É assim que podemos acessar e consumir facilmente um recurso de REST API usando o método GET e a classe %Net.HttpRequest. Este é um guia realmente amigável para iniciantes, que oferece uma "visão geral" de como fazemos isso. No entanto, aprender a magia das REST APIs é seu dever. É muito fácil brincar com tudo isso, então faça requisições e aprenda os outros métodos. Talvez no próximo guia possamos aprender como transferir dados de forma segura entre dois serviços por meio da arquitetura REST.

Espero que ajude alguém!