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, !
O que fizemos?
- Atribuímos a variável
request a uma nova instância do objeto %Net.HttpRequest.
- Atribuímos um local/endereço à propriedade Server na instância request.
- 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).
- 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.
- Atribuímos a variável response do próprio objeto request.
- Extraímos o status e o corpo.
- 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?
- Construindo uma requisição predefinida usando a classe.
- Tentando consumir os dados de que precisamos.
- Manipulando os cenários de falha e sucesso.
Se tudo correr bem, você deverá receber um objeto JSON como este:
.png)
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!