UltimoSDK 1.0.0

Introduction

This is a package to help develop against the Ultimo API in C#.

Install

To use this package you need to install it with npm, or download the repo and add the code to your project.

Usage

To use this SDK, there are a few steps to follow

Create a client

To create a client all you need is an api key and a portal uri like so

// Do make sure to add the v1/object to this uri
UltimoClient client = new(new Uri("https://www.portalUri.com"), "apiKey");

Execute requests

Once a client has been created you can start to execute request, this will show an example of how to get a list of jobs with a filter

UltimoListRequestData requestData = new()
{
    // This is one way to do it
    Filter = "Id eq \"0002\""

    // we could also use
    //Filters = new List<string>(){"Id eq \"0002\"", "Second filter"}
    // This uses a custom setter to set the Filter property
};
UltimoListResponse response = client.Execute<UltimoListResponse, UltimoListRequestData>(requestData, "Job") // Replace "Job" with endpoint add on e.g "ProcessFunction"

Read data or error from request

Once the response object has been obtained we can start to extract data from the response

if(response.Success == false){
    Console.WriteLine($"Request to Ultimo failed with message: {response.Message}");
    return;
}

foreach(JToken item in response.Items){
    // Do something with item
}

(Optional) Create Request data or Response data

If you want the SDK to return a specific type of item you can create your own data model for the response or request data with some limitations

Create your own response type

To create your own response type, you can pass it along in the UltimoListResponse or create a class that implements UltimoResponse

Example 1, using UltimoListResponse

// Create model class
public class UltimoExampleResponse{
        // Make sure to use the JsonProperty attribute,
        //  otherwise the json converter doesn't recognize the Property as a json field
        [JsonProperty("jsonPropertyName")] // e.g "id"
        public string? Id { get; set; }
}
// Execute the request as normal except that the type is given along with the UltimoListResponse Type
UltimoListResponse<UltimoExampleResponse> response = await client.ExecuteAsync<UltimoListResponse<UltimoExampleResponse>, UltimoListRequestData>(requestData, "Job");

// Now we can access the UltimoExample response item list again
// foreach(UltimoExampleResponse data in response.Items)
//{ Do something }

Example 2, Implementing UltimoResponse

// Create model class
public class UltimoExampleResponse : UltimoResponse
{
        // Make sure to use the JsonProperty attribute,
        //  otherwise the json converter doesn't recognize the Property as a json field
        [JsonProperty("jsonPropertyName")] // e.g "id"
        public string? Id { get; set; }
}

// Now execute the request as before
UltimoExampleResponse response = await client.ExecuteAsync<UltimoExampleResponse, UltimoListRequestData>(requestData, "Job");

// Check for success
if(response.Success){
    // Handle error
}

// And access the data
// response.Id;

Create request data

To create a different type of request data we implement the IUltimoRequestData interface This is just an empty interface, so the request can be any class that implements this empty interface.

// Create model class
public class UltimoExampleRequestData : IUltimoRequestData{
        // Make sure to use the JsonProperty attribute,
        //  otherwise the json converter doesn't recognize the Property as a json field
        [JsonProperty("jsonPropertyName")] // e.g "id"
        public string? Id { get; set; }
}

UltimoExampleRequestData requestData = new(){
    Id = "ExampleId"
};

// Execute request with new params
UltimoListResponse response = await client.ExecuteAsync<UltimoListResponse, UltimoExampleRequestData>(requestData, "Job");