Call external services with the HttpClient data type

You can integrate Business Central apps/extensions with external systems by using the HttpClient data type in your AL code.

The HttpClient data type is simply a wrapper on the .NET class HttpClient.

In this article, you learn how to make HTTP requests using the HttpClient data type and handle responses using the HttpResponseMessage data type.

Set up an external call

The first thing you need to do is to define the HTTP request, that is, which URI to call, set request and content HTTP headers, and choose which HTTP method to use. You do this using the HttpRequestMessage data type.

The following example illustrates ways to prepare the request.

    local procedure SendRequest(HttpMethod: Text[6]) ResponseText: Text
    var
        Client: HttpClient;
        HttpRequestMessage: HttpRequestMessage;
        RequestHeaders: HttpHeaders;
        RequestURI: Text;
        Content: HttpContent;
        ContentHeaders: HttpHeaders;
    begin
        RequestURI := 'https://httpcats.com/418.json';

        // This shows how you can set or change HTTP content headers in your request
        Content.GetHeaders(ContentHeaders);
        if ContentHeaders.Contains('Content-Type') then ContentHeaders.Remove('Content-Type');
        ContentHeaders.Add('Content-Type', 'multipart/form-data;boundary=boundary');

        // This shows how you can set HTTP request headers in your request
        HttpRequestMessage.GetHeaders(RequestHeaders);
        RequestHeaders.Add('Accept', 'application/json');
        RequestHeaders.Add('Accept-Encoding', 'utf-8');
        RequestHeaders.Add('Connection', 'Keep-alive');

        HttpRequestMessage.SetRequestUri(RequestURI);
        HttpRequestMessage.Method(HttpMethod);

        // from here on, the method must deal with calling out to the external service. 
        // see example code snippets below
    end;

For more information about content headers, see HttpContent data type.

Run the call

When you have set up the request, it's time to call out using a supported HTTP method.

The following example shows how to call an external web service from AL. It also illustrates the error handling you need to setup for handling errors when sending the request.

    local procedure GetRequest() ResponseText: Text
    var
        Client: HttpClient;
        Response: HttpResponseMessage;
        IsSuccessful: Boolean;
        ServiceCallErr: Label 'Web service call failed.';
        ErrorInfoObject: ErrorInfo;
    begin
        // assume you have setup the request here

        IsSuccessful := Client.Get('https://httpcats.com/418.json', Response);

        if not IsSuccessful then begin
            ErrorInfoObject.DetailedMessage := 'Sorry, we could not retrieve the cat info right now.';
            ErrorInfoObject.Message := ServiceCallErr;
            Error(ErrorInfoObject);
        end;
    end;

Supported HTTP methods

The HttpClient datatype supports the following HTTP methods:

• DELETE
• GET
• PATCH
• POST
• PUT

The following table includes links to help you get started with calling external services using different HTTP methods.

Parsing the result

If the HttpClient call succeeds, you get a response back from the service you called. The response is saved in the data type HttpResponseMessage, where you can parse it to use the information in your app. The service call itself might not succeed, so make sure that you check the HTTP status code in your AL code.

The following example illustrates the error handling you need to setup for handling errors from the service that you called.

    local procedure GetRequest() ResponseText: Text
    var
        Client: HttpClient;
        IsSuccessful: Boolean;
        ServiceCallErr: Label 'Web service call failed.';
        ErrorInfoObject: ErrorInfo;
    begin
        IsSuccessful := Client.Get('https://httpcats.com/418.json', HttpResponseMessage);

        if not IsSuccessful then begin
            // handle the error
        end;

        if not HttpResponseMessage.IsSuccessStatusCode() then begin
            HttpStatusCode := HttpResponseMessage.HttpStatusCode();
            ErrorInfoObject.DetailedMessage := 'Sorry, we could not retrieve the cat info right now. ';
            ErrorInfoObject.Message := Format(ServiceStatusErr, HttpStatusCode, HttpResponseMessage.ReasonPhrase());
            Error(ErrorInfoObject);
        end;

        HttpResponseMessage.Content().ReadAs(ResponseText);
    end;

HTTP status codes

When you try to access content on a server by using the HTTP protocol, it returns a numeric code that indicates the result of the request and semantics of the response, including whether the request was successful.

The first digit of the status code defines the class of response. The last two digits don't have any categorization role. There are five values for the first digit:

1xx (Informational): Provisional response - the request was received, continuing process.

2xx (Successful): The server successfully received and accepted the request.

3xx (Redirection): Further action needs to be taken in order to complete the request.

4xx (Client Error): The request contains an error and can't be fulfilled.

5xx (Server Error): The server failed to fulfill the request.

For more information, see HTTP Semantics

Common HTTP status error codes

When you call a web service endpoint, either a Business Central API or from AL using Httpclient datatype, you get an HTTP status code as part of the response. All HTTP status codes that start with 4 (sometimes also written 4xx) are classified as client errors and it is your responsibility to react on these errors and fix them in your code.

In the following table, we list some common 4xx HTTP status codes and suggestions to how to fix them:

Advanced scenarios

Using cookies

Starting from 2024 release wave 1, you can use server-side cookies when calling an external service using HttpClient This allows you to efficiently send and receive cookies in HTTP requests, unblocking scenarios where third-party endpoints require cookie customization. With the Cookie datatype and AL methods for handling cookies, you can automatically re-use response cookies, handle cookies manually, or a mix of both.

Using certificates

It's possible to include a certificate when calling an external service using HttpClient.

The following example shows how to add a certificate to the HttpClient data type.

// This code shows how to use certificates with HttpClient
procedure AddCertificateToHttpClient(var HttpClient: HttpClient; CertificateCode: Text[6])
var
    IsolatedCertificate: Record "Isolated Certificate";
    CertificateManagement: Codeunit "Certificate Management";
begin
    if not IsolatedCertificate.Get(CertificateCode) then
        exit;
    HttpClient.AddCertificate(
        CertificateManagement.GetCertAsBase64String(IsolatedCertificate),
        CertificateManagement.GetPassword(IsolatedCertificate));
end;

For more information about certificates, see

• HttpClient.AddCertificate Method
• Supported cipher suites in HTTPS.

Which IP addresses or ranges does my environment use?

When you exchange data through external services, you might have to safelist the IP addresses from where the Business Central service is running.

For more information, see

• FAQ: IP addresses or ranges for the Business Central service
• How-to restrict network access from/to Business Central.

Monitor and troubleshoot

Outgoing web service request telemetry gathers data about outgoing web service requests sent using the AL HTTPClient data type. This data gives you insight into the execution time and failures that happen in external services that your environment and extensions depend on. You can also use the data to alert on environments or apps for performance issues caused by external services, and be more proactive in preventing issues from occurring.

Application Insights

You can set up Business Central to send telemetry traces to an Application Insights resource in Azure. Once set up, telemetry data is sent to the resource when web services are called using the HttpClient data type. For more information, see, Analyzing outgoing web service request telemetry.

Troubleshoot errors

When calling external web services using the HttpClient module in AL, make sure that you handle the HTTP status code returned by the service in case of errors. For more information, see HttpHttpResponseMessage.HttpStatusCode() Method.

If you've enabled telemetry for your environment or app, you can use this KQL query to analyze errors in calls to external services.

traces
| where customDimensions has 'RT0019'
| extend httpStatusCode = toint( case( isnotempty(customDimensions.httpStatusCode), customDimensions.httpStatusCode, customDimensions.httpReturnCode ) )
| where httpStatusCode > 299
| summarize count() // how many calls fail
by httpStatusCode 
, endpoint = tostring( customDimensions.endpoint ) // which endpoint

Performance considerations

If you call an external web service using the HttpClient module in AL, be aware that the Business Central Server blocks the execution of AL code for the session until the call completes. For interactive sessions, this behavior means that the user sees a spinning wheel during the call.

If you have enabled telemetry for your environment or app, you can use this KQL query to analyze how much time users are delayed in the UI by calls to external services.

traces
| where customDimensions has 'RT0019'
| where customDimensions.clientType == 'WebClient'
| extend executionTimeInMs = toreal(totimespan(customDimensions.serverExecutionTime))/10000 //the datatype for executionTime is timespan
| summarize count() // how many calls
, sum(executionTimeInMs) // sum of delays for UI sessions
, avg(executionTimeInMs) // average waiting time by this app
, max(executionTimeInMs) // average waiting time by this app
by 
// which app is calling out from the UI
  extensionPublisher = tostring( customDimensions.extensionPublisher )
, extensionName = tostring( customDimensions.extensionName )
, extensionVersion = tostring( customDimensions.extensionVersion )

See also

Supported cipher suites in HTTPS
How-to restrict network access from/to Business Central
HttpClient data type
HttpContent data type
Analyzing outgoing web service request telemetry
Developing extensions
Get started with AL