How I Design Enterprise .NET APIs for Maintainability

Before opening a controller file, write down who calls the endpoint, what they need back, and what they will do with it. A surprising number of API problems disappear when the request and response shapes are designed around real consumers instead of database tables.

I treat the API surface as a contract that ships independently of the implementation. The implementation can be ugly today; the contract has to age well.

Never return entity types directly. Map to a DTO that says exactly what the API promises. The mapping layer is also the right place to enforce field-level authorization, omit internal fields, and stabilize naming.

When a consumer asks for a new field, the DTO is the single place to evaluate the request.

Version the API URL from day one (/v1/...). It is cheap up front and removes a class of future arguments. Reserve `additionalProperties: false` for inputs you control fully, and be tolerant on outputs.

Add a small `meta` envelope (request id, server time) on every response. It pays for itself the first time you debug a production incident.

Pick one error shape — usually a problem-details style object — and use it everywhere. Document the error codes that consumers should branch on. Avoid leaking exception messages.