A simple example of calling a JSON web service from AL

In this video, I show how to call a simple web service from Microsoft Dynamics 365 Business Central and how to process the JSON based reply.

https://youtu.be/D5jzrgl1EP0

In this video, Erik walks through how to make a simple API call from Business Central and parse the JSON response. The example uses the free ipify API to retrieve the public IP address of the Business Central server — a practical use case for when you need to configure firewall rules and want to know the outbound IP address of your BC environment.

The Use Case: Finding Your BC Server’s Public IP

The scenario is straightforward: sometimes you need to know the public IP address of your Business Central server, for example, when opening up firewall rules for external services. The ipify API is about as simple as it gets — you call https://api.ipify.org?format=json and you get a JSON response back with your IP address:

{"ip":"123.45.67.89"}

Building the Page

Erik starts by creating a blank project in Visual Studio Code and adds a new page file. The page is a simple Card page type with a single field that displays the IP address by calling a function. A few things to note about the page setup:

  • The page type is Card since we’re just displaying information, not editing records
  • The field is not editable — it simply displays the result of the GetIP() function
  • The page is added as an administration page so it’s searchable

Making the HTTP Call

The core of the implementation is the GetIP() function. Here’s what you need to understand about making HTTP calls in AL:

  • HttpClient — the object that makes the actual web request
  • HttpResponseMessage — holds the response from the server
  • JsonObject — used to parse the JSON response

One important point Erik highlights: when doing a simple GET request, you don’t need to use HttpRequestMessage at all. The HttpClient.Get() method only needs the URL and a response variable to put the result in. You would only need HttpRequestMessage if you needed to add custom headers or other configuration.

The flow is:

  1. Call Client.Get() with the URL
  2. Check if the response has a success status code
  3. Read the response content into a text variable
  4. Parse the text into a JSON object
  5. Extract the field you need from the JSON

The Code

While the source code provided with the video shows a separate API page for exposing Sales Line data, the code Erik builds live in the video is a simple card page that calls the ipify service. Here’s what that implementation looks like:

page 50700 "What Is My IP Address"
{
    PageType = Card;
    Caption = 'What is my IP Address';
    Editable = false;
    UsageCategory = Administration;
    ApplicationArea = All;

    layout
    {
        area(Content)
        {
            field(IP; GetIP())
            {
                ApplicationArea = All;
                Caption = 'Current IP Address of BC Server';
            }
        }
    }

    procedure GetIP(): Text
    var
        Client: HttpClient;
        Response: HttpResponseMessage;
        J: JsonObject;
        ResponseTxt: Text;
    begin
        // https://api.ipify.org?format=json
        if Client.Get('https://api.ipify.org?format=json', Response) then
            if Response.IsSuccessStatusCode then begin
                Response.Content.ReadAs(ResponseTxt);
                J.ReadFrom(ResponseTxt);
                exit(GetJsonTextField(J, 'ip'));
            end;
    end;

    procedure GetJsonTextField(JObject: JsonObject; MemberName: Text): Text
    var
        Result: JsonToken;
    begin
        if JObject.Get(MemberName, Result) then
            exit(Result.AsValue().AsText());
    end;
}

Understanding the JSON Parsing

Erik creates a helper function called GetJsonTextField to extract values from the JSON. This is a pattern worth understanding:

  • JsonObject — represents the curly brackets {} in JSON
  • JsonToken — the lowest-level element in the JSON structure. Every entity within the JSON object model is a token, which could be an array, value, or object
  • We call JObject.Get() which is a boolean function — it takes the key name and a variable to store the result
  • The token is then converted to a value with .AsValue() and finally to text with .AsText()

Erik also mentions that the ReadAs and ReadFrom direction of reading can be confusing — you read the response content into a text variable, then read that text into a JSON object. He references another video on the topic of understanding the “in and out” directions of these methods.

A Note on the API Page Pattern

The source code also includes an example of an API page, which is the other side of the coin — not calling an API, but exposing one from Business Central:

page 50140 APITest
{
    APIGroup = 'group';
    APIPublisher = 'hougaard';
    APIVersion = 'v2.0';
    ApplicationArea = All;
    Caption = 'apiTest';
    DelayedInsert = true;
    EntityName = 'salesheader';
    EntitySetName = 'salesheaders';
    PageType = API;
    SourceTable = "Sales Line";

    layout
    {
        area(content)
        {
            repeater(General)
            {
                field(documentNo; Rec."Document No.")
                {
                    Caption = 'Document No.';
                }
                field(documentType; Rec."Document Type")
                {
                    Caption = 'Document Type';
                }
                field("type"; Rec."Type")
                {
                    Caption = 'Type';
                }
                // ... additional fields
            }
        }
    }
}

This API page uses PageType = API and exposes Sales Line data with properties like APIGroup, APIPublisher, and APIVersion that define the endpoint URL structure.

Expanding Beyond the Basics

Erik notes that this example is intentionally simple. In real-world scenarios, you might need to:

  • Add URL parameters for more complex API calls
  • Use POST, PATCH, or PUT methods instead of GET
  • Add custom headers using HttpRequestMessage
  • Create additional helper functions like GetJsonBooleanField, GetJsonDecimalField, GetJsonOptionField, etc.
  • Add proper data validation to check if the response is actually valid JSON

Summary

Making a simple API call from Business Central requires just a few lines of code: use HttpClient to make the request, read the response content into a text variable, parse it into a JsonObject, and extract the fields you need using JsonToken. The helper function pattern for extracting typed values from JSON objects is reusable and can be expanded for different data types as needed. This is a great starting point for anyone looking to integrate external web services with Business Central.

Picture of hougaard

hougaard