klod68/api-contracts-standards

---

name: api-contracts-standards description: "Use when designing, reviewing, or enforcing interface-first API contracts, public API surfaces, or cross-library type signatures in .NET projects."

Skill: API Contracts & Interface-First Design Standards

Identity

| Field | Value | |---|---| | Name | API Contracts & Interface-First Design Standards | | Domain | API Design, Interfaces, Contracts | | Level | Feature | | Tags | api, contracts, interfaces, public-surface, dip |

When to Apply

Activate this skill when the task involves:

• Designing or reviewing public API surfaces
• Enforcing interface-first / contract-first design
• Cross-library type signatures (parameters and return types)
• Visibility rules (public vs internal sealed)
• DI registration across assembly boundaries

Rules

These rules layer on top of base architectural standards. On conflict, these win.

<!-- SHARED:rules/api-contracts.md -->

API Contracts & Interface-First Design — Standards

Apply these rules for all .NET projects. "Program to an interface, not to an implementation" is the load-bearing rule of the entire architecture.

---

Governing Principle

Define the contract before writing the implementation. An interface is a promise. It describes what a component does, not how. No implementation exists without a prior interface definition. Contracts defined after implementation are descriptive; contracts defined before are prescriptive. Only prescriptive contracts can be enforced by the Scaffolder, verified by the Reviewer, and independently implemented without coordination overhead.

---

The Interface-First Workflow

1. Designer defines interface → committed to design artifact
2. Scaffolder creates interface file + implementation shell
3. Implementer fills implementation — BOUND BY the interface, cannot alter it
4. Reviewer verifies: implementation matches interface EXACTLY

If an Implementer discovers a gap in the interface during implementation, they MUST surface it to the Designer — not silently add methods to the interface. Adding to an interface is a design decision, not an implementation decision.

---

Interface Definition Rules

Rule 1: One Concern Per Interface (ISP)

// Correct — segregated by concern
public interface I{Entity}Reader
{
    Task<{Entity}?> GetByIdAsync({EntityId} id, CancellationToken ct);
    Task<IReadOnlyList<{Entity}>> GetActiveAsync(CancellationToken ct);
}

public interface I{Entity}Writer
{
    Task AddAsync({Entity} entity, CancellationToken ct);
    Task UpdateAsync({Entity} entity, CancellationToken ct);
}

// Wrong — combined concerns force query handlers to depend on write methods
public interface I{Entity}Repository
{
    Task<{Entity}?> GetByIdAsync({EntityId} id, CancellationToken ct);
    Task AddAsync({Entity} entity, CancellationToken ct);
    Task<byte[]> ExportAsync({Entity} entity, CancellationToken ct); // unrelated concern
}

Rule 2: CancellationToken on Every Async Method

// Correct
public interface IExportService
{
    Task<byte[]> ExportAsync({Entity} entity, CancellationToken ct);
}

// Wrong — no CancellationToken
public interface IExportService
{
    Task<byte[]> ExportAsync({Entity} entity); // BLOCKER
}

CancellationToken must be the last parameter on every async interface method, named ct.

Rule 3: Return Abstractions, Accept Abstractions

// Correct — return read-only abstraction
Task<IReadOnlyList<{Entity}>> GetActiveAsync(CancellationToken ct);

// Wrong — concrete collection type leaks implementation detail
Task<List<{Entity}>> GetActiveAsync(CancellationToken ct);
Task<{Entity}[]> GetActiveAsync(CancellationToken ct);

| Return scenario | Correct type | |---|---| | Single item, may not exist | Task<{T}?> | | Single item, must exist | Task<{T}> | | Multiple items | Task<IReadOnlyList<{T}>> | | Paginated | Task<PagedResult<{T}>> | | Stream | IAsyncEnumerable<{T}> | | Operation result with possible failure | Task<Result<{T}>> |

Rule 4: Domain Types Only Cross Boundaries With Explicit Mapping

// Correct — query handler maps to DTO before crossing to Presentation
public async Task<{Entity}Dto> Handle(Get{Entity}ByIdQuery query, CancellationToken ct)
{
    var entity = await _reader.GetByIdAsync(new {EntityId}(query.Id), ct);
    return entity is null ? null : MapToDto(entity);
}

// Wrong — domain entity crosses into Presentation layer
public async Task<{Entity}> GetEntity(Guid id) // BLOCKER — entity in controller/component

Rule 5: Explicit Error Signaling via Result, Not Exceptions

// Correct — expected failures via Result
public interface I{Entity}Service
{
    Task<Result<{EntityId}>> CreateAsync(string title, CancellationToken ct);
    Task<Result> ArchiveAsync({EntityId} id, CancellationToken ct);
}

// Wrong — using exceptions for expected business failures
public interface I{Entity}Service
{
    Task<{EntityId}> CreateAsync(string title, CancellationToken ct);
    // caller must catch {Entity}NotFoundException — bad contract
}

---

Contract Completeness Standard

Before any interface is considered complete, it must satisfy:

| Check | Requirement | |---|---| | All async methods have CancellationToken ct as last parameter | Yes | | All async methods are suffixed with Async | Yes | | All return types are from the approved type table above | Yes | | No concrete types in parameters or return types (except domain entities in Application-layer interfaces) | Yes | | XML <summary> doc on the interface type | Yes | | XML <remarks> (UC-NNN / ADR-NNN) on the interface type | Yes |

---

Interface Placement Rules

| Interface Category | Location | |---|---| | Repository contracts | Application/Interfaces/Repositories/ | | Domain/application service contracts | Application/Interfaces/Services/ | | Domain-level contracts (e.g., IDomainEventDispatcher) | Domain/Common/ | | Presentation-only contracts (e.g., INavigationService) | Presentation/ |

Interfaces are NEVER defined in Infrastructure. Infrastructure only implements.

---

Versioning

When a breaking change to a public interface is required:

1. Create an ADR explaining why the break is necessary.
2. Introduce a new interface version: IExportService → IExportServiceV2 temporarily.
3. Migrate callers in a controlled sequence.
4. Remove the old interface in a subsequent pipeline run.
5. Never silently add parameters to existing interface methods.

---

Reviewer Fitness Functions

| Check | Signal | Severity | |---|---|---| | Missing CancellationToken | Async interface method without ct parameter | BLOCKER | | Concrete return type | List<T>, T[], Dictionary<K,V> in interface return | MAJOR | | Domain entity in Presentation | Entity type as action/component return type | BLOCKER | | Implementation adds public method not in interface | public method on class not declared in interface | MAJOR | | No XML doc on public interface | Interface without <summary> | MINOR | | Exception for expected failure | Interface method throws for not-found / validation | MAJOR | | Interface in Infrastructure layer | New public interface in any Infrastructure namespace | BLOCKER |

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Fat interface with 8+ methods | Split by read/write concern and by subject | | Missing ct on async method | Always include CancellationToken ct as last parameter | | List<T> or T[] return type | Use IReadOnlyList<T> or IAsyncEnumerable<T> | | Throwing for not-found in a repository | Return null or Result.Failure | | Defining an interface in Infrastructure | Move to Application/Interfaces/ | | Silent interface extension by Implementer | Surface to Designer; create ADR |

---

See Also

• api-design.md — RESTful conventions, HTTP methods, pagination, error responses
• cqrs.md — CQRS via MediatR, command/query separation, pipeline behaviors
• naming.md — Naming conventions for types, methods, properties, namespaces
• nullability.md — Nullable reference types, suppression discipline, collection rules
• design-patterns.md — Approved GoF patterns: Factory, Repository, Decorator, Strategy, Specification