HttpClient.Put(Text, HttpContent, var HttpResponseMessage) Method

Article
02/26/2024

Version: Available or changed with runtime version 1.0.

Sends a PUT request to the specified URI as an asynchronous operation.

Syntax

[Ok := ]  HttpClient.Put(Path: Text, Content: HttpContent, var Response: HttpResponseMessage)

Parameters

HttpClient
Type: HttpClient
An instance of the HttpClient data type.

Path
Type: Text
The path the request is sent to.

Content
Type: HttpContent
The HTTP request content sent to the server.

Response
Type: HttpResponseMessage
The response received from the remote endpoint.

Return Value

[Optional] Ok
Type: Boolean
Accessing the HttpContent property of HttpResponseMessage in a case when the request fails will result in an error. If you omit this optional return value and the operation does not execute successfully, a runtime error will occur.

Ways that HttpClient.Put calls can fail

The method HttpClient.Put can fail and return false in the following ways:

The requestUri is not an absolute URI.
The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.
The request failed due to timeout.

Important

Outbound HTTP calls from apps/extensions are blocked by default and must be approved for each extension, otherwise instead of an external call, the system will display the following error message: The request was blocked by the runtime to prevent accidental use of production services.

To enable outbound HTTP calls, go to the Extension Management page in Business Central, and choose Configure. Then, on the Extension Settings page, make sure that Allow HttpClient Requests is selected. This setting must be enabled for each app/extension, including library apps.

Example

The PUT request method either replaces an existing resource or creates a new one using request body payload. To make an HTTP PUT request, given an HttpClient and a URI, use the HttpClient.Put method:

    local procedure PutRequest(json: Text;) ResponseText: Text
    var
        Client: HttpClient;
        Content: HttpContent
        ContentHeaders: HttpHeaders;
        IsSuccessful: Boolean;
        Response: HttpResponseMessage;
        ResponseText: Text;
    begin
        Content.GetHeaders(ContentHeaders);

        if ContentHeaders.Contains('Content-Type') then headers.Remove('Content-Type');
        ContentHeaders.Add('Content-Type', 'application/json');

        if ContentHeaders.Contains('Content-Encoding') then headers.Remove('Content-Encoding');
        ContentHeaders.Add('Content-Encoding', 'UTF8');
        
        // assume that the json parameter contains the following data
        //
        // {
        //    userId = 1,
        //    id = 1,
        //    title = "foo bar",
        //    completed = false
        // }
        Content.WriteFrom(json);
        
        IsSuccessful := Client.Put('https://jsonplaceholder.typicode.com/todos/1', Content, Response);

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

        if not Response.IsSuccessStatusCode() then begin
            HttpStatusCode := response.HttpStatusCode();
            // handle the error (depending on the HTTP status code)
        end;

        Response.Content().ReadAs(ResponseText);

        // Expected output:
        //   PUT https://jsonplaceholder.typicode.com/todos/1 HTTP/1.1
        //   {
        //     "userId": 1,
        //     "id": 1,
        //     "title": "foo bar",
        //     "completed": false
        //   }
    end;

The preceding code:

Prepares a HttpContent instance with the JSON body of the request (MIME type of "application/json" and using the character encoding UTF8).
Makes a PUT request to "https://jsonplaceholder.typicode.com/todos/3".
Ensures that the response is successful.
Reads the response body as a string.

Content headers

By default, the content headers contain a header for 'Content-Type', namely 'text/plain; charset=utf-8'. This is important to adjust if the endpoint you're calling expects a different content type, for example, multipart/form-data or application/json.

The following AL code examples illustrate ways to change the content header.

    local procedure SendRequest(HttpMethod: Text[6]) ResponseText: Text
    var
        Client: HttpClient;
        Content: HttpContent;
        ContentHeaders: HttpHeaders;
    begin
        Content.GetHeaders(ContentHeaders);

        // If you want to set all the headers yourself, do it this way
        ContentHeaders.Clear();
        ContentHeaders.Add('Content-Type', 'multipart/form-data;boundary=boundary');

        // from here on, the method must deal with calling out to the external service. 
    end;

    local procedure SendRequest(HttpMethod: Text[6]) ResponseText: Text
    var
        Client: HttpClient;
        Content: HttpContent;
        ContentHeaders: HttpHeaders;
    begin
        Content.GetHeaders(ContentHeaders);

        // In this example, you just change the headers you need
        if ContentHeaders.Contains('Content-Type') then ContentHeaders.Remove('Content-Type');
        ContentHeaders.Add('Content-Type', 'multipart/form-data;boundary=boundary');

        // from here on, the method must deal with calling out to the external service. 
    end;

When calling an endpoint, 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. In the case of setting the wrong content type header, you'll typically receive the 415 Unsupported Media Type return code. This return code can also be due to the request's Content-Encoding header, or if the data you send doesn't match what the endpoint expects.

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.

To	See
Dynamically set the HTTP method from AL, set it on the HttpRequestMessage datatype and use the HttpClient.Send method to call the service.	HttpClient.Send(HttpRequestMessage, var HttpResponseMessage) Method HttpRequestMessage.Method([Text]) Method
Delete data in a service endpoint using the HTTP DELETE method.	HttpClient.Delete(Text, var HttpResponseMessage) Method
Read data from a service endpoint using the HTTP GET method.	HttpClient.Get(Text, var HttpResponseMessage) Method
Update data in a service endpoint using the HTTP PATCH method (no specific AL method exists for PATCH, so use HttpClient.Send).	HttpClient.Send(Text, HttpContent, var HttpResponseMessage) Method
Send data to a service endpoint using the HTTP POST method.	HttpClient.Post(Text, HttpContent, var HttpResponseMessage) Method
Send data to a service endpoint using the HTTP PUT method.	HttpClient.Put(Text, HttpContent, var HttpResponseMessage) Method