Codat.Platform 7.0.0

Codat.Platform

Manage the building blocks of Codat, including companies, connections, and more.

SDK Example Usage

Example

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;

var sdk = new CodatPlatform(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverUrl: string optional parameter when initializing the SDK client instance. For example:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;

var sdk = new CodatPlatform(
    serverUrl: "https://api.codat.io",
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

To authenticate with the API the authHeader parameter must be set when initializing the SDK client instance. For example:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;

var sdk = new CodatPlatform(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Error Handling

CodatPlatformException is the base exception class for all HTTP error responses. It has the following properties:

Some exceptions in this SDK include an additional Payload field, which will contain deserialized custom error data when present. Possible exceptions are listed in the Error Classes section.

Example

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Errors;
using Codat.Platform.Models.Requests;
using System;
using System.Net.Http;
using System.Net.Http.Headers;

var sdk = new CodatPlatform(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

try
{
    ListCompaniesRequest req = new ListCompaniesRequest() {
        Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
        OrderBy = "-modifiedDate",
        Tags = "region=uk && team=invoice-finance",
    };

    var res = await sdk.Companies.ListAsync(req);

    // handle response
}
catch (CodatPlatformException ex)  // all SDK exceptions inherit from CodatPlatformException
{
    // ex.ToString() provides a detailed error message
    System.Console.WriteLine(ex);

    // Base exception fields
    HttpResponseMessage rawResponse = ex.RawResponse;
    HttpResponseHeaders headers = ex.Headers;
    int statusCode = ex.StatusCode;
    string? contentType = ex.ContentType;
    var responseBody = ex.Body;

    if (ex is Codat.Platform.Models.Errors.ErrorMessage errorMessage) // different exceptions may be thrown depending on the method
    {
        // Check error data fields
        Codat.Platform.Models.Errors.ErrorMessagePayload payload = errorMessage.Payload;
        var errorStatusCode = payload.StatusCode;
        var service = payload.Service;
        // ...
    }

    // An underlying cause may be provided
    if (ex.InnerException != null)
    {
        Exception cause = ex.InnerException;
    }
}
catch (System.Net.Http.HttpRequestException ex)
{
    // Check ex.InnerException for network connectivity errors
    System.Console.WriteLine(ex.InnerException);
}

Error Classes

Primary exceptions:

• CodatPlatformException: The base class for HTTP error responses.
  • ErrorMessage: A Codat API error response. Its structured fields are on Payload.

Less common exceptions (3)

• System.Net.Http.HttpRequestException: Network connectivity error. For more details about the underlying cause, inspect the ex.InnerException.

• Inheriting from CodatPlatformException:

  • SDKException: The fallback exception if no more specific exception is matched.
  • ResponseValidationException: Thrown when the response data could not be deserialized into the expected type.

Retries

Every operation in this SDK retries failed requests with a default backoff strategy. By default it retries connection errors and responses with status 408, 429 or 5XX, starting at 500 ms and backing off by a factor of 1.5 up to 60 s between attempts, for at most an hour. You can override the retry strategy for a single call, or across the entire SDK.

To change the default retry strategy for a single API call, simply pass a RetryConfig to the call:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;
using Codat.Platform.Utils.Retries;

var sdk = new CodatPlatform(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(
    retryConfig: new RetryConfig(
        strategy: RetryConfig.RetryStrategy.BACKOFF,
        backoff: new BackoffStrategy(
            initialIntervalMs: 1L,
            maxIntervalMs: 50L,
            maxElapsedTimeMs: 100L,
            exponent: 1.1
        ),
        retryConnectionErrors: false
    ),
    request: req
);

// handle response

If you'd like to override the default retry strategy for all operations, you can use the RetryConfig optional parameter when initializing the SDK:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;
using Codat.Platform.Utils.Retries;

var sdk = new CodatPlatform(
    retryConfig: new RetryConfig(
        strategy: RetryConfig.RetryStrategy.BACKOFF,
        backoff: new BackoffStrategy(
            initialIntervalMs: 1L,
            maxIntervalMs: 50L,
            maxElapsedTimeMs: 100L,
            exponent: 1.1
        ),
        retryConnectionErrors: false
    ),
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Custom HTTP Client

The C# SDK makes API calls through an ICodatHttpClient. The default implementation, CodatHttpClient, wraps the native HttpClient.

You can extend CodatHttpClient, or provide your own ICodatHttpClient implementation with customized configuration such as custom message handlers, timeouts, connection pooling, and other HTTP client settings.

The following example shows how to extend the default client to modify each request and handle errors:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;
using Codat.Platform.Utils;
using System;
using System.Net.Http;
using System.Threading.Tasks;

var sdk = new CodatPlatform(
    client: new CustomHttpClient(),
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

public class CustomHttpClient : CodatHttpClient
{
    public override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
    {
        request.Headers.Add("x-custom-header", "custom value");

        try
        {
            var response = await base.SendAsync(request);
            Console.WriteLine($"Request successful: {response.StatusCode}");
            return response;
        }
        catch (Exception error)
        {
            Console.WriteLine($"Request failed: {error.Message}");
            throw;
        }
    }
}

You can also provide a completely custom HTTP client with your own configuration:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;
using Codat.Platform.Utils;
using System;
using System.Net.Http;
using System.Threading.Tasks;

var sdk = new CodatPlatform(
    client: new AdvancedHttpClient(),
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

public class AdvancedHttpClient : ICodatHttpClient
{
    private readonly HttpClient _httpClient;
    private readonly CodatHttpClient _defaultClient = new CodatHttpClient();

    public AdvancedHttpClient()
    {
        var handler = new HttpClientHandler()
        {
            MaxConnectionsPerServer = 10,
        };

        _httpClient = new HttpClient(handler)
        {
            Timeout = TimeSpan.FromSeconds(30)
        };
    }

    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
    {
        return await _httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
    }

    public Task<HttpRequestMessage> CloneAsync(HttpRequestMessage request)
    {
        return _defaultClient.CloneAsync(request);
    }
}

For simple debugging, you can enable request/response logging by wrapping another client:

using Codat.Platform;
using Codat.Platform.Models.Components;
using Codat.Platform.Models.Requests;
using Codat.Platform.Utils;
using System;
using System.Net.Http;
using System.Threading.Tasks;

var sdk = new CodatPlatform(
    client: new LoggingHttpClient(),
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

public class LoggingHttpClient : ICodatHttpClient
{
    private readonly ICodatHttpClient _innerClient;

    public LoggingHttpClient(ICodatHttpClient? innerClient = null)
    {
        _innerClient = innerClient ?? new CodatHttpClient();
    }

    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request)
    {
        Console.WriteLine($"Sending {request.Method} request to {request.RequestUri}");

        var response = await _innerClient.SendAsync(request);

        Console.WriteLine($"Received {response.StatusCode} response");

        return response;
    }

    public Task<HttpRequestMessage> CloneAsync(HttpRequestMessage request)
    {
        return _innerClient.CloneAsync(request);
    }
}

The SDK also runs hooks before each request and after each response or error. Register your own on sdk.SDKConfiguration.Hooks with RegisterBeforeRequestHook, RegisterAfterSuccessHook or RegisterAfterErrorHook, passing an implementation of the matching interface from Codat.Platform.Hooks.

Support

If you encounter any challenges while utilizing our SDKs, please don't hesitate to reach out for assistance. You can raise any issues by contacting your dedicated Codat representative or reaching out to our support team. We're here to help ensure a smooth experience for you.