Web APIs, REST & gRPC

I describe REST as an architectural style rather than a synonym for JSON over HTTP. Its constraints are client-server separation, stateless requests, cacheability, a uniform interface, layering, and optional code on demand. I identify resources with stable URIs and use representations and standard HTTP semantics. Strict REST also includes hypermedia-driven transitions. In practice, I would be clear whether an API follows all those constraints or is a pragmatic resource-oriented HTTP API.

I use stable plural nouns such as orders and products, with identifiers for individual resources. Query parameters handle filtering, sorting and pagination. I nest paths only when ownership or context is useful, such as a customer's orders, and avoid deeply nested URLs. For an operation such as cancellation, I may create a cancellation resource or use a documented action. I design around the business contract rather than exposing database table structure directly.

I use safe to mean that the requested operation does not change resource state, as with GET and HEAD. Logging can still happen as an incidental side effect. Idempotent means repeating an identical request has the same intended server effect as sending it once. PUT and DELETE are idempotent but unsafe. Responses may differ between attempts, so a DELETE returning 204 and then 404 can still be idempotent.

I normally use POST to create a resource under a collection or initiate processing, especially when the server chooses its URI. PUT replaces the writable representation at a known URI and is idempotent. PATCH applies a partial modification according to a defined patch format. I do not assume PATCH is idempotent: setting a status repeatedly can be, but incrementing a quantity is not. For concurrent updates I also consider conditional requests using ETags.

I return 201 when a new order is created and normally include its URI in Location. If processing is accepted but unfinished, I use 202 and provide a way to check progress. A successful operation without response content can return 204. Invalid input uses the documented 400 or 422 policy, a state conflict can use 409, and a failed If-Match precondition uses 412. I avoid hiding all outcomes behind 200.

I return 401 when the request needs valid authentication credentials, for example because a bearer token is missing or invalid, with the appropriate authentication challenge. I use 403 when authorization refuses the operation, usually after the caller has authenticated. For sensitive resources I may deliberately return 404 to avoid disclosing existence, following a consistent policy. In all cases I check access to the specific order, not just whether the caller has a valid token.

I require a stable idempotency key per logical payment and scope it to the caller and operation. A unique database constraint arbitrates concurrent requests, and I store a payload hash to reject key reuse with different input. Completed attempts replay the recorded response, while in-progress behavior and expiry are documented. Local changes commit atomically. For an external payment provider I also reuse its idempotency mechanism and reconcile uncertain outcomes rather than assuming my database transaction covers the remote charge.

I use offset for small administrative lists and direct access to numbered pages. For large feeds, cursor pagination avoids traversing a growing number of skipped rows. I use a deterministic sort, such as creation time plus a unique numeric identifier, and a matching index. The cursor captures both values and is tied to the filters. It reduces insert-related paging problems but does not create snapshot consistency when records themselves change, and arbitrary page jumps become harder.

I define a small, explicit vocabulary of filter fields, operators and sort directions instead of accepting arbitrary query expressions. I validate types, cap page sizes and apply authorization scope before filtering and paging. Values become parameters, while dynamic identifiers come from an allowlist. I also consider supporting indexes and query cost, because a syntactically valid filter can still be expensive. Stable ordering and documented cursor behavior make the endpoint predictable for clients.

I choose a consistent strategy, often a path segment for visibility, and document deprecation and retirement dates. Removing fields, changing types, adding required input or changing established behavior can break clients. Optional additions are usually compatible only if clients tolerate unknown fields and values. I use schema diffs and consumer contract tests to check that assumption. Before retiring a version I measure real usage and coordinate migration instead of relying only on a published date.

I write and review the HTTP contract before implementation, including schemas, status codes, authentication and error responses. Teams can then use mocks and generated clients while the service is being built. CI checks for incompatible schema changes, and behavioral tests verify guarantees the schema cannot express. In .NET 10 I can use built-in OpenAPI generation to compare the implementation with the agreed document, but generating documentation alone does not make the process contract-first.

I treat an API schema as one part of a broader specification. The specification explains the user outcome, business rules, authorization, failure scenarios and acceptance criteria. I resolve ambiguity before planning implementation, then turn the criteria into reviewable tasks and tests. OpenAPI captures the HTTP boundary, while operational guarantees such as retry safety need additional detail. The value comes from shared, testable expectations, whether implementation is written by a person or assisted by an agent.

I use ProblemDetails to give clients a recognizable error structure rather than unrelated strings from each endpoint. The standard fields describe the problem type, title, status and occurrence, and I can add a stable application code and trace identifier. Clients should branch on stable semantics, not parse human-readable messages. I keep sensitive diagnostics in logs. ASP.NET Core provides registration and exception handling support, but I still define mappings for expected domain failures.

I use AsyncAPI to document an event interface: channels, message schemas, send and receive operations, and relevant protocol bindings. It gives producers and consumers a shared contract, much as OpenAPI does for HTTP. I still document delivery behavior separately, including ordering scope, retries, duplicate handling and schema evolution. The document can support tooling and validation, but it does not implement a broker or guarantee exactly-once processing for business side effects.

I verify the provider's signature over the exact raw payload, validate its timestamp and compare signatures in constant time. I rotate secrets and deduplicate event identifiers because signatures do not stop replay. After durable inbox storage I acknowledge promptly and process asynchronously. The sender uses bounded retries with backoff and jitter, and we support dead-letter inspection and replay. I design state transitions for duplicate and out-of-order events and protect configurable callback destinations against SSRF.

I choose SSE for one-way server updates such as progress or order status, especially when ordinary HTTP streaming fits the infrastructure. WebSockets suit bidirectional, frequent messages but leave more protocol work to the application. SignalR gives me hubs, groups and transport negotiation on top of those concerns. I also plan authentication, proxy timeouts, reconnection, backpressure and scale-out. None of these choices alone provides durable message delivery or automatic recovery of every missed event.

I distinguish unary calls from server streaming, client streaming and bidirectional streaming. The proto contract generates typed APIs, and streaming lets messages flow without creating a new request for each item. I set deadlines, propagate cancellation and account for slow consumers. Native gRPC is a good fit between controlled services, but browser clients usually need gRPC-Web or a gateway, and supported streaming modes differ. I verify the complete network path rather than assuming HTTP/2 support everywhere.

I start with client needs and interaction patterns. REST works well for public resources and HTTP caching. GraphQL helps clients request different graph-shaped views, but requires cost controls and careful resolver authorization. gRPC suits typed internal calls and streaming when clients and infrastructure support it. SignalR fits interactive push to connected users. I compare operational cost, compatibility and measured workloads, and may combine styles rather than force one mechanism to serve every boundary.

I see HATEOAS as a way for representations to advertise available transitions through meaningful links. A client can discover that an order can currently be cancelled instead of hard-coding every transition URL. It still needs to understand relation and payload semantics, and the server must recheck authorization and state when the action runs. I use it when discoverability and long-lived client evolution justify the added representation design and tooling, rather than adding decorative links without client benefit.

I check authentication, object and tenant authorization, DTO boundaries, validation, parameterization and resource limits. I test that one customer cannot access another customer's order, even with its identifier. I review retry safety for payments, webhook verification, cache policies and error redaction. I also check rate limits, timeouts, telemetry and dependency maintenance. CORS is only a browser access policy, and cookie-authenticated mutations need CSRF protection. Finally, I run compatibility tests against the published contract.