as a developer who uses Cache as DB for couple of projects I'm using REST API's every time, so knowing how to consume a resource from REST API and in my opinion its crucial to know how to consume external REST Api's using %Net.HttpRequest because its enables integration with modern web application and serveries and its crucial skill for a backend developer who love and used Cache as 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 contain the response in the same pattern.
a proper way to handle REST Api request with %Net involved checking both %Status returned value and the response status codes that's let you raise specific error messages and filter the responses why the request is failed when needed, 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 handeling.
before we got our hands dirty, we should know who is JSONPlaceHolder, 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 a 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 how to consume a JSON from 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 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" that's means we request data from "posts" with id equal to 1 (to get just the first message, we can specify just "posts" and got all of them, it's good to play with it)
- check if there way any error on 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 its 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-case 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 form REST API, but what we can 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 GET method and %Net.HttpRequest class, this is really beginner friendly guide who let you "overview" on how we do it but learn the magic of REST APIs is your duty, everything here is easy to play with so just make a requests and learn the other methods and maybe in the next guide we can learn how to securely transfer data between two services over REST architecture
Hope is help for someone! (Sorry if had a lot of mistakes while writing English it's not my native language and I got burned before will I using LLM to make it looks good.)
