Somum.Requests 10.1.6

Somum.Requests

Somum.Requests provides base request types and URI construction helpers for Somum API contracts. Derive a request from QueryBase<TResponse> for read operations or CommandBase<TResponse> for state-changing operations.

QueryBase<TResponse> is the abstract base class used for GET queries.

Build a request URI

Override Endpoint with the resource path and, when necessary, Version with the API version. Mark public properties with FromQuery to include their non-null values in the query string. Supply Name to FromQuery when the API parameter name differs from the property name.

using Microsoft.AspNetCore.Mvc;
using Somum.Requests;

public sealed class GetJobsRequest : QueryBase<IReadOnlyList<Job>>
{
    protected override string Endpoint => "jobs";

    protected override int Version => 2;

    [FromQuery(Name = "page")]
    public int? Page { get; init; }

    [FromQuery(Name = "pageSize")]
    public int? PageSize { get; init; }
}

var request = new GetJobsRequest { Page = 1, PageSize = 25 };

var queryString = request.ToQueryString();
// page=1&pageSize=25

var relativeUri = request.GetUri("messaging");
// messaging/api/v2/jobs?page=1&pageSize=25

var url = request.GetUrl("https://api.example.com", "messaging");
// https://api.example.com/messaging/api/v2/jobs?page=1&pageSize=25

API behavior

GetUrl requires an absolute HTTP or HTTPS host and rejects hosts containing a query string or fragment. Leading and trailing path separators are normalized when the URL is combined.

Query-string values

Query values are converted by QueryStringBuilder. Values are not URL-encoded, so encode values before assigning them to a FromQuery property when the API requires encoded text.

Navigating Queries

NavigatingQuery<T> provides the following query parameters for paginated, filtered, and ordered results:

For filtering and ordering expression syntax, refer to the Gridify documentation.

Commands with HTTP Request Payloads

Use CommandBase<TResponse, TPayload> for POST and PUT requests that include a JSON body payload. The Payload property is automatically marked with [FromBody], allowing ASP.NET Core to bind the HTTP request body to the command.

Example `PUT` endpoint:

````````markdown

Example HTTP request:

````````markdown

The JSON request body is bound to `command.Payload`, while route, query string, and form values can be defined as additional properties on the command.

Paged Results

Paged<T> is the standard response model for paginated API endpoints. It contains the page data, total item count, paging details, and optional navigation links.

Response