Designing an API-First .NET Platform for Web, POS, Admin and Partner Integrations

API-first is a business architecture decision

When several applications depend on the same products, customers, prices and orders, the backend becomes more than an implementation detail. It becomes a contract between teams and channels.

An API-first platform starts by defining capabilities such as CalculateCart, ReserveInventory, ConfirmBooking and RefundOrder. These contracts describe business intent. They do not simply expose tables.

Design resources around business behaviour

A weak API often mirrors the database. A strong API mirrors the workflow.

POST /api/orders/{orderId}/refund
POST /api/bookings/{bookingId}/confirm
POST /api/pricing/calculate
POST /api/inventory/reservations

These routes communicate intent. They also give the server a natural place to enforce validation, permissions, idempotency and audit behaviour.

Treat DTOs as contracts, not database entities

public sealed record CalculateCartRequest(
    int ShopId,
    long? CustomerId,
    IReadOnlyCollection<CartItemRequest> Items);

public sealed record CartItemRequest(
    long ProductId,
    int Quantity,
    long? AttributeOptionId);

API contracts should remain deliberate even when the database changes. That reduces accidental coupling between the frontend release cycle and internal schema evolution.

Version only when the contract truly breaks

Versioning is useful, but permanent version multiplication creates its own maintenance problem. Prefer additive change where possible: optional fields, new endpoints and backward-compatible behaviour. Introduce a new version when client expectations can no longer be preserved safely.

Design commands for retries

POST /api/orders
Idempotency-Key: 601b7424-d6c7-43ca-a5c8-e7afce62db5a

Clients retry because networks fail. Payment, booking and order APIs should explicitly decide what a repeated request means rather than leaving duplicate behaviour to chance.

Make every important request traceable

A platform API should emit correlation identifiers, structured logs and business-level telemetry. When an order fails, the team should be able to reconstruct the request path across pricing, inventory, payment and database dependencies.

Business value

References