As a developer who uses Cache as DB for a couple of projects, I'm using REST API's every time, knowing how to consume a resource from REST API, in my opinion, it's crucial to know how to consume external REST Api's using %Net.HttpRequest because it enables integration with modern web applications and services, and it's a crucial skill for a backend developer who loves and uses Cache as a DB.
What and who is %Net.HttpRequest
its just a class but this is the proper way of making request outside of the framework, this is just a simple class who provide HTTP methods like GET, POST and PUT and all others request methods, let you "play" with the headers and craft the request as you want to and how to handle the response you got, for every request send using %Net.HttpRequest, we got in return a %Net.HttpResponse object that contains the response in the same pattern.
A proper way to handle REST Api requests with %Net involves checking both the %Status returned value and the response status codes, which let you raise specific error messages and filter the responses when the request fails. The recommended way is to use macros like $$$ISER() or $SYSTEM.Status.IsOK(), we can use $SYSTEM.Status.DisplayError() to inspect the HTTP status code for handling.
Before we get our hands dirty, we should know who JSONPlaceHolder is, so from the official site, they said:
"Free fake and reliable API for testing and prototyping"
And it is what it is, it's a free online REST API to play with, it's fake data, and we can even POST data to it, but this guide is all about consuming data, so let's focus on that, and this is a simple example of how to consume a JSON from a REST API Service:
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, !
What do we do?
- Assign "request" from a new instance of %New.HttpRequest object
- Assign a location/address to the property Server on the request instance.
- Making a GET request to the endpoint we provided to the function "/posts/1", which means we request data from "posts" with id equal to 1 (to get just the first message, we can specify just "posts" and get all of them, it's good to play with it)
- Check if there is any error in the function using $$$ISERR with the status returned from the request GET method. If there is none, the request was sent successfully from our endpoint.
- Assign the response variable from the request object itself.
- Extract the status and the body.
- Check if the response code is OK If the code returned is above 200 and below or equal to 300, it's OK. (307 is redirecting, so it's less what we need here)
So, in a general perspective, what are we doing here?
- Craft a pre-defined request using the class
- trying to consume the data we needed
- Handle both use cases of failure and success
If everything goes well, you should get something like this as a JSON object:
.png)
And this is how we consume data from a REST API, but what can we do with it?
Let's see how to extract the data from the response:
Set reponseBodyAsJSON = {}.%FromJSON(body)
Write "id: ", reponseBodyAsJSON.id, !
Write "title: ", reponseBodyAsJSON.title, !
Write "body: ", reponseBodyAsJSON.body, !
In this way, we break the response into key-value pairs like JSON should be.
This is how we can easily access and consume a REST API resource using the GET method and %Net.HttpRequest class, this is a really beginner-friendly guide that lets you "overview" how we do it.
Learning the magic of REST APIs is your duty.
Since this topic is very approachable, you can easily experiment by making requests and trying out different methods. In the next guide, we’ll look at how to securely transfer data between two REST-based services.
