Why should you care?

Without contracts, Payment breaks when Order renames a field silently. Contracts let teams develop in parallel.

See it live — copy this example

Create a Web API project (dotnet new webapi), paste the code, then run dotnet run.

// ShopNest.Contracts/Orders/CreateOrderRequest.cs
public record CreateOrderRequest(
    Guid CustomerId,
    IReadOnlyList<OrderLineRequest> Lines);

public record OrderCreatedResponse(Guid Id, string Status, decimal Total);

// Order.Api implements exactly this shape

Run Example »

This lesson uses terminal or setup steps. Run commands on your computer — the live editor appears on coding lessons.

What happened?

• Shared contract project holds DTOs only — no database, no business logic.
• Version contracts when you must break clients.

Try it yourself

1. Create ShopNest.Contracts class library.
2. Add CreateOrderRequest and OrderCreatedResponse records.
3. Reference Contracts from Order.Api and from a future Gateway.
4. Change a string or number in the example and run again — predict the output first.
5. Break the code on purpose (remove a semicolon), read the compiler error, then fix it.

Remember

Contracts = public DTOs between services. Keep contracts thin — no EF, no HTTP clients. Version when breaking; prefer additive changes.

Real-world: Mobile app + BFF

Android app depends on stable OrderCreatedResponse. Backend team adds field — old apps ignore it; never rename id to orderId without version.

Outcome: Contract tests in CI catch breaking JSON before production.