Codeunit 2350 Rest Client

// ------------------------------------------------------------------------------------------------
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.
// ------------------------------------------------------------------------------------------------
namespace System.RestClient;

/// <summary>Provides functionality to easily work with the HttpClient object.</summary>
codeunit 2350 "Rest Client"
{
    Access = Public;
    InherentEntitlements = X;
    InherentPermissions = X;

    var
        RestClientImpl: Codeunit "Rest Client Impl.";

    #region Constructors
    /// <summary>Initializes a new instance of the Rest Client class.</summary>
    /// <returns>The Rest Client object.</returns>
    /// <remarks>The default Http Client Handler and anonymous Http authentication will be used.</remarks>
    procedure Create(): Codeunit "Rest Client"
    begin
        RestClientImpl := RestClientImpl.Create();
        exit(this);
    end;

    /// <summary>Initializes a new instance of the Rest Client class.</summary>
    /// <param name="HttpClientHandler">The Http Client Handler to use.</param>
    /// <returns>The Rest Client object.</returns>
    /// <remarks>The anynomous Http Authentication will be used.</remarks>
    procedure Create(HttpClientHandler: Interface "Http Client Handler"): Codeunit "Rest Client"
    begin
        RestClientImpl := RestClientImpl.Create(HttpClientHandler);
        exit(this);
    end;

    /// <summary>Initializes a new instance of the Rest Client class.</summary>
    /// <param name="HttpAuthentication">The authentication to use.</param>
    /// <returns>The Rest Client object.</returns>
    /// <remarks>The default Http Client Handler will be used.</remarks>
    procedure Create(HttpAuthentication: Interface "Http Authentication"): Codeunit "Rest Client"
    begin
        RestClientImpl := RestClientImpl.Create(HttpAuthentication);
        exit(this);
    end;

    /// <summary>Initializes a new instance of the Rest Client class.</summary>
    /// <param name="HttpClientHandler">The Http Client Handler to use.</param>
    /// <param name="HttpAuthentication">The authentication to use.</param>
    /// <returns>The Rest Client object.</returns>
    procedure Create(HttpClientHandler: Interface "Http Client Handler"; HttpAuthentication: Interface "Http Authentication"): Codeunit "Rest Client"
    begin
        RestClientImpl := RestClientImpl.Create(HttpClientHandler, HttpAuthentication);
        exit(this);
    end;
    #endregion

    #region Initialization
    /// <summary>Initializes the Rest Client with the default Http Client Handler and anonymous Http authentication.</summary>
    procedure Initialize()
    begin
        RestClientImpl.Initialize();
    end;

    /// <summary>Initializes the Reest Client with the given Http Client Handler</summary>
    /// <param name="HttpClientHandler">The Http Client Handler to use.</param>
    /// <remarks>The anynomous Http Authentication will be used.</remarks>
    procedure Initialize(HttpClientHandler: Interface "Http Client Handler")
    begin
        RestClientImpl.Initialize(HttpClientHandler);
    end;

    /// <summary>Initializes the Rest Client with the given Http Authentication.</summary>
    /// <param name="HttpAuthentication">The authentication to use.</param>
    /// <remarks>The default Http Client Handler will be used.</remarks>
    procedure Initialize(HttpAuthentication: Interface "Http Authentication")
    begin
        RestClientImpl.Initialize(HttpAuthentication);
    end;

    /// <summary>Initializes the Rest Client with the given Http Client Handler and Http Authentication.</summary>
    /// <param name="HttpClientHandler">The Http Client Handler to use.</param>
    /// <param name="HttpAuthentication">The authentication to use.</param>
    procedure Initialize(HttpClientHandler: Interface "Http Client Handler"; HttpAuthentication: Interface "Http Authentication")
    begin
        RestClientImpl.Initialize(HttpClientHandler, HttpAuthentication);
    end;

    /// <summary>Sets a new value for an existing default header of the Http Client object, or addds the header if it does not already exist.</summary>
    /// <param name="Name">The name of the request header.</param>
    /// <param name="Value">The header of request header.</param>
    /// <remarks>Default request headers will be added to every request that is sent with this Rest Client instance
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    procedure SetDefaultRequestHeader(Name: Text; Value: Text)
    begin
        RestClientImpl.SetDefaultRequestHeader(Name, Value);
    end;

    /// <summary>Sets a new value for an existing default header of the Http Client object, or addds the header if it does not already exist.</summary>
    /// <param name="Name">The name of the request header.</param>
    /// <param name="Value">The header of request header.</param>
    /// <remarks>Default request headers will be added to every request that is sent with this Rest Client instance
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    procedure SetDefaultRequestHeader(Name: Text; Value: SecretText)
    begin
        RestClientImpl.SetDefaultRequestHeader(Name, Value);
    end;

    /// <summary>Sets the base address of the Rest Client.</summary>
    /// <remarks>The base address will be used for every request that is sent with this Rest Client instance.
    /// Calls to the Get, Post, Patch, Put and Delete methods must  use a relative path which will be appended to the base address.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    /// <param name="Url">The base address to use.</param>
    procedure SetBaseAddress(Url: Text)
    begin
        RestClientImpl.SetBaseAddress(Url);
    end;

    /// <summary>Gets the base address of the Rest Client.</summary>
    /// <returns>The base address of the Rest Client.</returns>
    procedure GetBaseAddress() Url: Text
    begin
        Url := RestClientImpl.GetBaseAddress();
    end;

    /// <summary>Sets the timeout of the Rest Client.</summary>
    /// <param name="Timeout">The timeout to use.</param>
    /// <remarks>The timeout will be used for every request that is sent with this Rest Client instance.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    procedure SetTimeOut(Timeout: Duration)
    begin
        RestClientImpl.SetTimeOut(Timeout);
    end;

    /// <summary>Gets the timeout of the Rest Client.</summary>
    /// <returns>The timeout of the Rest Client.</returns>
    procedure GetTimeOut() Timeout: Duration
    begin
        Timeout := RestClientImpl.GetTimeOut();
    end;

    /// <summary>Adds a certificate to the Rest Client.</summary>
    /// <param name="Certificate">The Base64 encoded certificate</param>
    /// <remarks>The certificate will be used for every request that is sent with this Rest Client instance.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    procedure AddCertificate(Certificate: Text)
    begin
        RestClientImpl.AddCertificate(Certificate);
    end;

    /// <summary>Adds a certificate to the Rest Client.</summary>
    /// <param name="Certificate">The Base64 encoded certificate</param>
    /// <param name="Password">The password of the certificate</param>
    /// <remarks>The certificate will be used for every request that is sent with this Rest Client instance.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>

    procedure AddCertificate(Certificate: Text; Password: SecretText)
    begin
        RestClientImpl.AddCertificate(Certificate, Password);
    end;

    /// <summary>Sets the use of server certificate validation.</summary>
    /// <param name="Value">If true, the server certificate validation is enabled. False to disable</param>
    /// <remarks>Use this function to enable or disable the server certificate validation.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    procedure SetUseServerCertificateValidation(Value: Boolean)
    begin
        RestClientImpl.SetUseServerCertificateValidation(Value);
    end;

    /// <summary>Sets the user agent header of the Rest Client.</summary>
    /// <remarks>Use this function to overwrite the default User-Agent header.
    /// The default user agent header is "Dynamics 365 Business Central - |[Publisher]| [App Name]/[App Version]".
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    /// <param name="Value">The user agent header to use.</param>
    procedure SetUserAgentHeader(Value: Text)
    begin
        RestClientImpl.SetUserAgentHeader(Value);
    end;

    /// <summary>Sets the authorization header of the Rest Client.</summary>
    /// <remarks>Use this function to set the authorization header.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    /// <param name="Value">The authorization header to use.</param>
    procedure SetAuthorizationHeader(Value: SecretText)
    begin
        RestClientImpl.SetAuthorizationHeader(Value);
    end;

    /// <summary>Sets the use of response cookies in subsequent requests.</summary>
    /// <remarks>Use this function to enable or disable automatically attach cookies received in the response to all subsequent requests.
    /// The Rest Client will be initialized if it was not initialized before.</remarks>
    /// <param name="Value">If true, the client automatically attaches cookies received in the response to all subsequent requests. False to disable</param>
    procedure SetUseResponseCookies(Value: Boolean)
    begin
        RestClientImpl.SetUseResponseCookies(Value);
    end;
    #endregion

    #region BasicMethods
    /// <summary>Sends a GET request to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <returns>The response message object</returns>
    procedure Get(RequestUri: Text) HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := Send(Enum::"Http Method"::GET, RequestUri);
    end;

    /// <summary>Sends a POST request to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send.</param>
    /// <returns>The response message object</returns>
    procedure Post(RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := Send(Enum::"Http Method"::POST, RequestUri, Content);
    end;

    /// <summary>Sends a PATCH request to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send.</param>
    /// <returns>The response message object</returns>
    procedure Patch(RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := Send(Enum::"Http Method"::PATCH, RequestUri, Content);
    end;

    /// <summary>Sends a PUT request to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send.</param>
    /// <returns>The response message object</returns>
    procedure Put(RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := Send(Enum::"Http Method"::PUT, RequestUri, Content);
    end;

    /// <summary>Sends a DELETE request to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <returns>The response message object</returns>
    procedure Delete(RequestUri: Text) HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := Send(Enum::"Http Method"::DELETE, RequestUri);
    end;
    #endregion

    #region BasicMethodsAsJson
    /// <summary>Sends a GET request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails with a collectible error if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure GetAsJson(RequestUri: Text) JsonToken: JsonToken
    begin
        JsonToken := RestClientImpl.GetAsJson(RequestUri);
    end;

    /// <summary>Sends a POST request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonObject.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PostAsJson(RequestUri: Text; Content: JsonObject) Response: JsonToken
    begin
        Response := PostAsJson(RequestUri, Content.AsToken());
    end;

    /// <summary>Sends a POST request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonArray.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PostAsJson(RequestUri: Text; Content: JsonArray) Response: JsonToken
    begin
        Response := PostAsJson(RequestUri, Content.AsToken());
    end;

    /// <summary>Sends a POST request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonToken.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PostAsJson(RequestUri: Text; Content: JsonToken) Response: JsonToken
    begin
        Response := RestClientImpl.PostAsJson(RequestUri, Content);
    end;

    /// <summary>Sends a PATCH request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonObject.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PatchAsJson(RequestUri: Text; Content: JsonObject) Response: JsonToken
    begin
        Response := PatchAsJson(RequestUri, Content.AsToken());
    end;

    /// <summary>Sends a PATCH request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonArray.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PatchAsJson(RequestUri: Text; Content: JsonArray) Response: JsonToken
    begin
        Response := PatchAsJson(RequestUri, Content.AsToken());
    end;

    /// <summary>Sends a PATCH request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonToken.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PatchAsJson(RequestUri: Text; Content: JsonToken) Response: JsonToken
    begin
        Response := RestClientImpl.PatchAsJson(RequestUri, Content);
    end;

    /// <summary>Sends a PUT request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonObject.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PutAsJson(RequestUri: Text; Content: JsonObject) Response: JsonToken
    begin
        Response := PutAsJson(RequestUri, Content.AsToken());
    end;

    /// <summary>Sends a PUT request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonArray.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PutAsJson(RequestUri: Text; Content: JsonArray) Response: JsonToken
    begin
        Response := PutAsJson(RequestUri, Content.AsToken());
    end;

    /// <summary>Sends a PUT request to the specified Uri and returns the response content as JsonToken.</summary>
    /// <remarks>The function fails with an error message if the request could not be sent or a response was not received.
    /// The function also fails with a collectible error in case the response does not contain a success status code.
    /// In case the response contains no content, an empty JsonToken is returned. 
    /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send as a JsonToken.</param>
    /// <returns>The response content as JsonToken</returns>
    procedure PutAsJson(RequestUri: Text; Content: JsonToken) Response: JsonToken
    begin
        Response := RestClientImpl.PutAsJson(RequestUri, Content);
    end;
    #endregion

    #region GenericSendMethods
    /// <summary>Sends a request with the specific Http method and an empty content to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="Method">The HTTP method to use.</param>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <returns>The response message object</returns>
    procedure Send(Method: Enum "Http Method"; RequestUri: Text) HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := RestClientImpl.Send(Method, RequestUri);
    end;

    /// <summary>Sends a request with the specific Http method and the given content to the specified Uri and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.
    /// If a response was received, then the response message object contains information about the status.</remarks>
    /// <param name="Method">The HTTP method to use.</param>
    /// <param name="RequestUri">The Uri the request is sent to.</param>
    /// <param name="Content">The content to send.</param>
    /// <returns>The response message object</returns>
    procedure Send(Method: Enum "Http Method"; RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := RestClientImpl.Send(Method, RequestUri, Content);
    end;

    /// <summary>Sends the given request message and returns the response message.</summary>
    /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.</remarks>
    /// <param name="HttpRequestMessage">The request message to send.</param>
    /// <returns>The response message object</returns>
    procedure Send(var HttpRequestMessage: Codeunit "Http Request Message") HttpResponseMessage: Codeunit "Http Response Message"
    begin
        HttpResponseMessage := RestClientImpl.Send(HttpRequestMessage);
    end;

    #endregion
}