api-and-interface-design

API and Interface Design

Overview

Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. This applies to REST APIs, gRPC services, NuGet package surface area, assembly boundaries, record/DTO shapes, and any surface where one piece of code talks to another.

When to Use

• Designing new HTTP endpoints (Minimal APIs or controllers)
• Defining module boundaries or contracts between projects in a solution
• Creating public types in MyApp.Contracts or a shared NuGet library
• Establishing database schemas that inform DTO shape
• Changing existing public interfaces (especially in a published NuGet package)

Core Principles

Hyrum's Law

With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.

This means: every public behavior — including undocumented quirks, exception messages, response ordering, and even the presence of unused fields in a JSON response — becomes a de facto contract once users depend on it. Design implications:

• Be intentional about what you expose. Mark types internal unless a consumer outside the assembly truly needs them. Every observable behavior is a potential commitment.
• Don't leak implementation details. Don't return EF Core entities directly from HTTP endpoints — project to DTOs (MyApp.Contracts) so schema changes to the entity don't break consumers.
• Plan for deprecation at design time. See deprecation-and-migration for how to safely remove things users depend on.
• Tests are not enough. Even with perfect contract tests, Hyrum's Law means "safe" changes can break real users who depend on undocumented behaviour (an exact error string, the order of a List<T> returned from a LINQ query, the presence of a nullable field that was always null).