New Endpoint

New Endpoint Skill

The goal is to make every new endpoint feel native to the SDK: same folder structure, same monadic flow, same validation story, same test layout, same documentation bar. A customer should never be able to tell which engineer wrote a use case.

The SDK follows screaming architecture: products are modules, and every module is a collection of use cases. A single use case owns a folder and contains one or two request types, an optional builder, and an optional response. Tests mirror this layout exactly.

Before you touch any code

1. STOP and gather inputs

Ask the user, then wait for answers:

1. What is the product? (existing module like VerifyV2, Conversations, or a new module.)
2. What is the use case? (e.g., CreateTemplate, GetBroadcasts.) Use an imperative verb + subject — matches folder/class naming.
3. Is there an OpenAPI spec? If yes, ask for the path. Use it as the source of truth for: endpoint path, HTTP method, required vs optional fields, character limits, enum values, formats, and response shape.
4. Code-snippets URL. The canonical pattern is https://github.com/Vonage/vonage-dotnet-code-snippets/tree/master/DotNetCliCodeSnippets/<Product>. Assume this URL using the product name and ask the user to confirm it's correct before committing — the snippets repo isn't always in sync with the SDK, so don't add a <seealso> to a URL you haven't verified.
5. Authentication: which header does this API use? Basic / Bearer (JWT) / OIDC-bearer / custom. Determines which VonageHttpClientConfiguration to wire up in VonageClient.PropagateCredentials().
6. Base URL / region: Nexmo API, Video API, OIDC API, or a regional variant (EMEA / APAC / AMER)?

Do not start coding until you have at least answers 1, 2, 4, 5, 6. Guessing the endpoint path or auth type means rewriting everything later.

2. Locate the closest blueprint

Pick the existing use case that most resembles what you're about to build and read it end-to-end before writing a line. Blueprints by shape:

Matching a blueprint is not optional — it keeps the SDK homogeneous.

Folder layout (screaming architecture)

For a new use case Xxx under product Product:

Vonage/
  Product/
    IProductClient.cs               # interface (public)
    ProductClient.cs                # implementation (internal)
    XxxResponse.cs                  # ONLY if shared across use cases (e.g. GetXxx + CancelXxx return same type)
    Xxx/
      XxxRequest.cs                 # readonly partial struct, [Builder] if applicable
      XxxRequestBuilder.cs          # ONLY if NOT using [Builder] generator
      XxxResponse.cs                # record or readonly struct; omit for Unit responses or if shared at product level
Vonage.Test/
  Product/
    E2EBase.cs                      # shared helper per product
    XxxResponseSerializationTest.cs # ONLY if response type is shared across use cases
    Data/
      ShouldDeserialize200-response.json  # ONLY if serialization test lives at product level
    Xxx/
      E2ETest.cs
      RequestTest.cs
      RequestBuilderTest.cs
      SerializationTest.cs          # ONLY for use-case-specific request/response shapes
      Data/
        ShouldSerialize-request.json
        ShouldDeserialize200-response.json
        (more as needed)

Never put two use cases in the same folder, and never flatten the structure even for trivial endpoints — screaming architecture is the rule.

Group related support types into subfolders. When a product namespace accumulates many related types that are not themselves use cases — capability records, webhook types, discriminated-union members, configuration POCOs — move them into a named subfolder with a matching sub-namespace (e.g. Vonage/Product/Capabilities/ with namespace Vonage.Product.Capabilities). The threshold is roughly 5+ cohesive types; a flat directory of 20+ files with no grouping is a smell. The sub-namespace must be added as a using wherever those types are referenced.

When a response type is shared across multiple use cases (e.g. GET /reports/{id} and DELETE /reports/{id} both return the same shape), place the response record at the product level (Vonage/Product/XxxResponse.cs) and its serialization test at Vonage.Test/Product/XxxResponseSerializationTest.cs with the fixture in Vonage.Test/Product/Data/. Do not duplicate the serialization test inside each use case folder — that's dead weight. The E2EBase for that product can then initialise its SerializationTestHelper from the product-level namespace so E2E tests reference the shared fixture via nameof(XxxResponseSerializationTest.ShouldDeserialize200).

Outside-in TDD order

Write the tests first, in this order. Each step's test drives the next layer down.

Step 1 — SerializationTest.cs and fixtures

This is the contract with the wire. Write it first because both the request shape and the response type are implied by the JSON fixtures.

1. Create Data/ShouldSerialize-request.json from the OAS example (or the API docs). Copy the JSON verbatim; include exactly the keys the builder is expected to emit.
2. Create Data/ShouldDeserialize200-response.json from the OAS example.
3. Write ShouldSerialize — builds the request with the builder, calls GetStringContent(), compares to this.helper.GetRequestJson().
4. Write ShouldDeserialize200 — deserializes the fixture into the response type and asserts key fields.

Pattern:

[Trait("Category", "Serialization")]
[Trait("Product", "Product")]
public class SerializationTest
{
    private readonly SerializationTestHelper helper = new(
        typeof(SerializationTest).Namespace,
        JsonSerializerBuilder.BuildWithSnakeCase()); // or BuildWithCamelCase() — match the API

    [Fact]
    public void ShouldSerialize() =>
        XxxRequest.Build()
            .WithFoo("bar")
            .Create()
            .GetStringContent()
            .Should()
            .BeSuccess(this.helper.GetRequestJson());

    [Fact]
    public void ShouldDeserialize200() => this.helper.Serializer
        .DeserializeObject<XxxResponse>(this.helper.GetResponseJson())
        .Should()
        .BeSuccess(VerifyExpectedResponse);

    private static void VerifyExpectedResponse(XxxResponse response) { /* field asserts */ }
}

Rules:

• One request fixture per scenario you intend to serialize (ShouldSerialize, ShouldSerializeWithRequiredFieldsOnly …). The filename must match the test name: <testName>-request.json or <testName>-response.json.
• ShouldSerialize must set every field (all mandatory + all optional) and the fixture must contain all of them. A partial fixture is a lie — it hides wiring bugs where optional fields are silently omitted from the body. If there are many optional fields, also add ShouldSerializeWithRequiredFieldsOnly to test the minimal body. Expose BuildRequest() and BuildRequestWithRequiredFieldsOnly() as internal static on RequestBuilderTest so the serialization test and E2E test can reuse the same builder call without duplication.
• Fixtures named after the test allow E2ETest to re-use them via this.Serialization.GetRequestJson(nameof(SerializationTest.ShouldSerialize)).
• If multiple E2E tests build the same request, expose a helper returning Result<XxxRequest> marked internal static on SerializationTest — CreateConversation/SerializationTest.cs does this with BuildRequest().
• For request-only endpoints (e.g. DELETE), only the deserialize-response test is needed if there's a response body; otherwise skip.
• Every variant of a polymorphic or union-like field needs its own serialization test. When a request or response contains a field that can hold different sub-types (e.g. a capabilities object whose properties are each a different type, a discriminated union, or a collection of independent optional sub-objects), add one dedicated [Fact] per variant — not just one test that happens to combine two of them. One combined fixture that exercises Voice + Messages does not prove that RTC, Verify, Video, Meetings, NetworkApis, or VBC serialize correctly. The name pattern is ShouldSerializeWith<Variant> and each has its own matching fixture file in Data/. No variant may be left untested — a missing variant means zero guarantee it round-trips through the serializer.

Step 2 — RequestBuilderTest.cs

Drive out the builder. One test per rule, success and failure paths. Use [Theory] / [InlineData] for repeated value matrices.

Mandatory coverage — no exceptions:

• Happy path for every setter: Create_ShouldSet<Property>.
• Defaults for every optional property: Create_ShouldHaveNo<Property>_GivenDefault (asserts Maybe.None) or Create_ShouldSet<Property>ToDefault_... (for [OptionalWithDefault]). Every [Optional] field needs both its default test AND its setter test. Skipping "less interesting" optional fields is a TDD violation.
• Every validation rule, asserting the exact failure message with BeParsingFailure("<message>.").
• When many optional fields create repetition, extract a BuildBase() private static helper that returns IBuilderForOptional with mandatory fields pre-filled, so each test is one fluent chain.
• No comments of any kind in test files. This includes section markers like // DateStart, // Optional fields, or #region. Test methods are self-documenting through their names; comments become misleading as code is reorganised.

Phrasing of failure messages is generated by InputValidation helpers, so copy-paste exactly:

Use .BeSuccess(value => ...) for nested assertions and .BeSuccess(expected) when you can compare with equality.

Step 3 — RequestTest.cs

Thin test that asserts BuildRequestMessage().RequestUri resolves to the right path (including any interpolated IDs, query string, etc.).

HAL link → request round-trip. Whenever a paginated response exposes a next, prev, first, or last link, customers must be able to reconstruct a new request directly from that URL — otherwise they have to decompose and re-assemble the query string themselves, which is terrible DX.

The pattern: replace the plain ReportLink (or similar href-only type) in the response with a typed HAL link record that owns a BuildRequest() method. BuildRequest() calls HttpUtility.ParseQueryString(uri.Query), extracts every recognised parameter, and feeds them through the same [Builder]-generated fluent interface used by customers:

public record XxxHalLink(Uri Href)
{
    public Result<XxxRequest> BuildRequest()
    {
        var p = ParseQueryParameters(this.Href);
        IBuilderForOptional builder = XxxRequest.Build()
            .WithMandatoryField(p.MandatoryValue);
        builder = p.OptionalField.Match(builder.WithOptionalField, () => builder);
        // ... repeat for every field present in the URL
        return builder.Create();
    }
    ...
}

Include these RequestTest cases for the HAL link:

1. Happy path — constructs a XxxHalLink from a URL that includes all relevant query parameters and asserts the resulting request has the expected field values.
2. Missing mandatory field — constructs from a URL where a required parameter is absent and asserts BeParsingFailure("FieldName cannot be null or whitespace.").

All-parameters URI test. For GET endpoints with many optional query parameters, add one [Fact] that builds a request with every optional field set to a representative value, then parses the resulting URI with HttpUtility.ParseQueryString and asserts each key-value pair. This catches wiring bugs (missing IfSome, wrong key name) that per-field setter tests do not catch because they test one field in isolation. Parsing the query string (rather than string-matching the full URL) avoids encoding fragility. Requires using System.Linq; and using System.Web;.

[Fact]
public void RequestUri_ShouldContainAllParameters() =>
    XxxRequest.Build()
        .WithMandatory("value")
        .WithOptionalA("a")
        .WithOptionalB(EnumValue)
        ...
        .Create()
        .Map(r => r.BuildRequestMessage().RequestUri!.ToString())
        .Should()
        .BeSuccess(uri =>
        {
            var q = HttpUtility.ParseQueryString(uri.Split('?').Last());
            q["optional_a"].Should().Be("a");
            q["optional_b"].Should().Be("enum-description");
            ...
        });

Pagination E2E test. When a response contains HAL navigation links, add an E2E test that:

1. Mocks the first-page response (containing a next link).
2. Extracts the next request via firstPage.Bind(r => r.Links.Next.BuildRequest()).
3. Passes that directly to the client method and asserts the second call succeeds.

This proves the round-trip works end-to-end through WireMock — the link URL is deserialized, parsed back into a request, serialized as query parameters, and matched by the server stub. Use Result<T>.Bind (not Map) so parsing failures propagate.

Use HalLinks<XxxHalLink> (from Vonage.Common) for the response Links property when the API returns multiple navigation links (self, next, prev, etc.). Use snake_case serializer: Self → "self", Next → "next". When the fixture URL must contain URL-encoded characters (e.g. + in a date offset), encode them explicitly in the fixture string so deserialization round-trips correctly.

[Fact]
public void RequestUri_ShouldReturnApiEndpoint() =>
    XxxRequest.Build()
        .WithId(new Guid("06547d61-7ac0-43bb-94bd-503b24b2a3a5"))
        .Create()
        .Map(request => request.BuildRequestMessage().RequestUri!.ToString())
        .Should()
        .BeSuccess("/v2/verify/06547d61-7ac0-43bb-94bd-503b24b2a3a5");

Step 4 — E2ETest.cs

Uses WireMock via the shared E2EBase for the product. Asserts the full round-trip: that the SDK emits the exact bytes expected by the API, hits the right URL with the right auth header, and deserializes the response correctly.

Pattern:

[Trait("Category", "E2E")]
[Trait("Product", "Product")]
public class E2ETest() : E2EBase(typeof(E2ETest).Namespace)
{
    [Fact]
    public async Task Xxx()
    {
        this.Helper.Server.Given(WireMock.RequestBuilders.Request.Create()
                .WithPath("/v2/verify/.../xxx")
                .WithHeader("Authorization", this.Helper.ExpectedAuthorizationHeaderValue)
                .WithBody(this.Serialization.GetRequestJson(nameof(SerializationTest.ShouldSerialize)))
                .UsingPost())
            .RespondWith(Response.Create().WithStatusCode(HttpStatusCode.OK)
                .WithBody(this.Serialization.GetResponseJson(nameof(SerializationTest.ShouldDeserialize200))));
        await this.Helper.VonageClient.ProductClient
            .XxxAsync(XxxRequest.Build().With...().Create())
            .Should()
            .BeSuccessAsync(response => /* assert */);
    }
}

Stream response assertions. When the method under test returns Task<Result<Stream>>, do not assert BeAssignableTo<Stream>() — it is trivially true and verifies nothing about the actual response content. Instead, read the stream and compare it to the value the WireMock stub returned:

await this.Helper.VonageClient.ProductClient
    .DownloadXxxAsync(XxxRequest.Build().WithFileId(fileId).Create())
    .Should()
    .BeSuccessAsync(stream =>
    {
        using var reader = new StreamReader(stream);
        reader.ReadToEnd().Should().Be("expected-body-content");
    });

Set the WireMock stub's .WithBody("expected-body-content") to a short, known string (e.g. "zip-content") — not real binary — so the assertion stays readable and deterministic.

Add an E2EBase.cs for the product the first time you add one:

public class E2EBase
{
    internal readonly TestingContext Helper;
    internal readonly SerializationTestHelper Serialization;

    protected E2EBase(string serializationNamespace) : this() => this.Serialization =
        new SerializationTestHelper(serializationNamespace, JsonSerializerBuilder.BuildWithSnakeCase());

    protected E2EBase() => this.Helper = TestingContext.WithBearerCredentials(); // or WithBasicCredentials()
}

Pick credentials to match the product's auth type (Bearer for JWT-based APIs, Basic for api_key/api_secret APIs).

Production code

Request type

Always a public readonly partial struct (the partial is required for the source generator). Implements IVonageRequest.

[Builder]
public readonly partial struct XxxRequest : IVonageRequest
{
    // properties with [Mandatory] / [Optional] etc...

    public HttpRequestMessage BuildRequestMessage() => VonageRequestBuilder
        .Initialize(HttpMethod.Post, $"/v2/things/{this.Id}")
        .WithContent(this.GetRequestContent())
        .Build();

    private StringContent GetRequestContent() =>
        new(JsonSerializerBuilder.BuildWithSnakeCase().SerializeObject(this),
            Encoding.UTF8, "application/json");

    [ValidationRule]
    internal static Result<XxxRequest> VerifyFoo(XxxRequest request) =>
        InputValidation.VerifyNotEmpty(request, request.Foo, nameof(request.Foo));
}

Conventions:

• C# property names must be customer-friendly, not OAS/wire names. When the OAS field name is an abbreviation or jargon (trx, moCallBackUrl, drCallBackUrl, msisdn, etc.), expand it to a clear English name (TransactionReference, InboundSmsCallbackUrl, DeliveryReceiptCallbackUrl, PhoneNumber, …). The wire name stays unchanged — put it in [JsonPropertyName], the GetUrlEncoded() string literal, or the query-parameter key. Customers read the C# API; they never see the transport encoding.
• Properties use { get; internal init; } — public get, internal init so the only way to construct is via the builder (and thus go through validation).
• readonly partial struct — never class, never public init.
• Use JsonPropertyOrder on every serialized property when field order in the output JSON matters (it often does for assertions and fixtures).
• Use JsonIgnore + MaybeJsonConverter<T> on Maybe<T> properties that should be omitted when None.
• Use EnumDescriptionJsonConverter<T> for enums that serialize via [Description] attributes.
• URI interpolation goes in BuildRequestMessage(). Query strings go through UriHelpers.BuildUri(path, dict).
• Do not use nullable reference annotations (T?) on reference types unless #nullable enable is active in the project. The project does not enable nullable reference types, so writing string?, VoiceCapability?, or any other reference-type nullable triggers CS8632 warnings. Reference types are implicitly nullable without the annotation — just write string, VoiceCapability, etc. The only ? allowed here is on genuine value types: int?, bool?, Guid?, enum types (which are value types and use Nullable<T>). Check for #nullable enable in the .csproj before annotating any reference type; when in doubt, grep -r "Nullable" Vonage/Vonage.csproj.
• Aggregate types own their own predicates. If the request must decide whether to include an aggregate (e.g. only add "capabilities" to the body when at least one capability is set), put that predicate on the aggregate type itself — not inside GetRequestContent(). A HasCapabilities / IsEmpty bool property on the aggregate keeps the request's assembly logic clean and makes the predicate independently testable. Test it with dedicated [Theory] cases covering the empty state and every individual field that makes it true.
• When rewriting or paralleling an existing type, audit what the original encodes. Before writing a new version of a capability, webhook, or configuration type, read the existing implementation for:
  • Default values (e.g. Voice webhook timeouts default to 1000 ms connection / 500 ms socket — drop this and callers silently get server defaults instead).
  • HTTP-method restrictions (e.g. Messages, Verify, and Meetings webhooks are POST-only — the old code hard-coded POST to prevent invalid state; model this with a dedicated PostOnlyWebhook type rather than a generic webhook that accepts GET).
  • Other invariants or constraints encoded as narrower types. Silently dropping these business rules is invisible to tests unless the tests are also written with them in mind.
• Pick BuildWithSnakeCase() or BuildWithCamelCase() to match the product. When in doubt, copy the setting from the sibling use case in the same product — every Vonage API team has its own conventions and company-wide rules aren't always enforced, so never assume based on "the norm". Current per-product defaults below (verify by reading a neighbour before you copy):

Builders — prefer the source generator

Use [Builder] on the struct and attribute each settable property. The generator emits:

• An interface IBuilderForX per mandatory field (staged / phantom types so missing mandatory fields are a compile error).
• A final IBuilderForOptional interface with every optional setter plus Create().
• The internal XxxRequestBuilder struct.

Compound optional fields: prefer individual optionals over a single aggregate. When a request field is itself an aggregate type whose sub-components are each independently optional (e.g. a capabilities object where Voice, Messages, RTC, … are each optional), do not model it as a single [Optional] Maybe<CapabilitiesType> that forces the caller to construct the aggregate manually. Instead, expose each sub-component as its own [Optional] property on the request struct:

[Optional] public Maybe<VoiceCapability>    Voice      { get; internal init; }
[Optional] public Maybe<MessagesCapability> Messages   { get; internal init; }
[Optional] public Maybe<RtcCapability>      Rtc        { get; internal init; }

The generator emits individual WithVoice(...), WithMessages(...), WithRtc(...) methods — callers chain only what they need. The GetRequestContent() implementation assembles the aggregate internally using with expressions, then decides whether to include it in the body based on a HasXxx predicate (see responsibility placement below). This pattern gives far better DX than forcing callers to construct a large initializer block for the aggregate.

When to hand-roll the builder instead. Always prefer [Builder] when it fits. Drop it and write an explicit XxxRequestBuilder.cs only when the shape genuinely can't be expressed with the existing attributes — for example:

• Multiple builder methods mutating the same collection (WithNumber(...) is called repeatedly — see CreateConversationRequest).
• Conditional validation that inspects another property (requires matching on Maybe inside a rule).
• Parsing that needs to cross-reference another input.

The hand-rolled builder follows the same structure — phantom interfaces for mandatory stages, final IBuilderForOptional, an internal struct named XxxRequestBuilder that implements both. See Vonage/Conversations/CreateConversation/.

We own the source generator. The Vonage.SourceGenerator project lives in this repo, so if a near-miss pattern shows up a second or third time, extending the generator (new attribute, variant, or behaviour) is often the right call rather than hand-rolling yet another builder. Before writing a bespoke builder, ask the user whether it's worth teaching the generator the new trick. Past additions (MandatoryWithParsing, OptionalBoolean, OptionalWithDefault, OptionalWithParsing) all started as one-offs that became patterns.

Validation

Place each rule as an internal static Result<T> method on the request struct, decorated with [ValidationRule]. The generator wires them into the builder's Create(). InputEvaluation<T>.WithRules(...) runs all rules and aggregates failures into ParsingFailure — do not short-circuit by hand.

[ValidationRule]
internal static Result<XxxRequest> VerifyName(XxxRequest request) =>
    InputValidation.VerifyNotEmpty(request, request.Name, nameof(request.Name));

[ValidationRule]
internal static Result<XxxRequest> VerifyNameLength(XxxRequest request) =>
    InputValidation.VerifyLengthLowerOrEqualThan(request, request.Name, 80, nameof(request.Name));

Favor the helpers in InputValidation over raw ResultFailure.FromErrorMessage, so error messages stay consistent.