Q9 — REST API Design — HTTP Verbs, Status Codes, and ProblemDetails
Level: Junior to Intermediate | Topic: Web API Best Practices and Design
Designing robust, maintainable, and client-friendly REST APIs using C# and ASP.NET Core is a fundamental skill for modern backend engineers. This article expands on the foundation of HTTP verb semantics, standard status codes, and the use of RFC 7807 ProblemDetails for error responses. Alongside enriched explanations, diagrams, code examples, and observability insights, this guide empowers you to design APIs that are easy to evolve and consume.
HTTP Verb Semantics: A Core Principle for RESTful APIs
At its heart, REST API design leverages the uniform interface defined by HTTP. Each HTTP method (verb) expresses the intent of an operation and interacts with resources accordingly. Let’s start by revisiting and extending the core HTTP methods with their correct usage and typical status code expectations.
| HTTP Verb | Intended Action | Idempotent? | Typical Success Status Codes | Common Error Status Codes |
|---|---|---|---|---|
| GET | Read resource(s) | Yes | 200 OK, 404 Not Found | 400 Bad Request (malformed URI) |
| POST | Create new resource | No | 201 Created + Location header | 422 Unprocessable Entity (validation), 409 Conflict (duplicate) |
| PUT | Full replacement of resource | Yes | 204 No Content or 200 OK | 404 Not Found, 422 Unprocessable Entity |
| PATCH | Partial update | No/few idempotent, depends on implementation | 204 No Content | 404 Not Found, 422 Unprocessable Entity |
| DELETE | Remove resource | Yes | 204 No Content or 404 Not Found | 409 Conflict (if resource is referenced) |
Important HTTP Semantic Notes
- GET should never change server state. It is strictly for retrieval.
- POST is non-idempotent: typically used to create new resources. Calling a POST twice may create duplicate resources.
- PUT replaces an entire resource: partial updates require PATCH.
- PATCH is the only HTTP verb designed for partial updates. Implement cautiously and document clearly.
- DELETE may be idempotent or return 404 if the resource does not exist on subsequent calls.
ProblemDetails (RFC 7807) for Machine-Readable Error Responses
RFC 7807 standardizes error response payloads enabling clients to handle errors programmatically and consistently. ASP.NET Core offers a built-in ProblemDetails class to serialize error information in a structured JSON format.
Core Fields of ProblemDetails
| JSON Property | Description |
|---|---|
type | A URI reference to human-readable documentation for the error type (optional). |
title | A short, human-readable summary of the problem type. |
status | HTTP status code returned from the server. |
detail | A detailed explanation specific to this occurrence of the problem (optional). |
instance | A URI reference that identifies the specific occurrence of the problem (optional). |
Why Use ProblemDetails?
- Clients can parse and react to errors consistently.
- Enables rich error information without relying solely on status codes.
- Supports extensibility with custom fields (via subclasses).
- Standardized by an IETF RFC and supported widely.
REST API High-Level Architecture (HLD)
flowchart TD
A[Client] -->|HTTP Request| B[API Gateway/Load Balancer]
B --> C[API Controllers (OrdersController)]
C --> D[Business Logic (IOrderService)]
D --> E[Data Access Layer / Repository]
E --> F[Database / Persistent Storage]
subgraph ErrorHandling
direction LR
C --> G[ProblemDetails Generation]
G --> A
endFigure 1: High level data flow in a typical C# ASP.NET Core REST API.
- Client sends HTTP requests using standardized HTTP verbs.
- API Gateway handles routing, rate limiting, authentication, and load balancing.
- Controllers map HTTP routes and verbs to application logic.
- Services encapsulate business rules.
- Data Access abstracts database interactions.
Error generation flows back to the client via ProblemDetails or other payloads with proper HTTP codes.
Interaction Sequence for Order Creation API
sequenceDiagram
participant Client
participant APIController as OrdersController
participant Service as IOrderService
participant Database
Client->>APIController: POST /api/v1/orders with request body
APIController->>Service: CreateAsync(request)
Service->>Database: Insert order record
Database-->>Service: Order created with new Id
Service-->>APIController: Return OrderDto with Id
APIController-->>Client: 201 Created + Location: /api/v1/orders/{id} + body OrderDtoFigure 2: Sequence diagram illustrating the order creation flow in the REST API.
Detailed Code Examples in ASP.NET Core
Now let's look at two expanded, meaningful examples of how you can design your controller actions with proper verb semantics, status codes, and ProblemDetails for errors.
Minimal Working Example: GET /orders/{id}
[HttpGet("{id:guid}", Name = "GetOrderById")]
[ProducesResponseType(typeof(OrderDto), 200)]
[ProducesResponseType(typeof(ProblemDetails), 404)]
public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
{
var order = await _service.GetByIdAsync(id, ct);
return order is null
? NotFound(new ProblemDetails
{
Title = "Order Not Found",
Detail = $"No order found with Id {id}",
Status = 404,
Instance = HttpContext.Request.Path
})
: Ok(order);
}
Notice how the action returns
ProblemDetailsfor the 404 case instead of a bare status code, improving error transparency.
Realistic and Robust Example: POST /orders (Create Order)
[HttpPost]
[ProducesResponseType(typeof(OrderDto), 201)]
[ProducesResponseType(typeof(ValidationProblemDetails), 422)]
[ProducesResponseType(typeof(ProblemDetails), 500)]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest req, CancellationToken ct)
{
if (!ModelState.IsValid)
return ValidationProblem(ModelState); // returns 422 with ValidationProblemDetails payload
try
{
var order = await _service.CreateAsync(req, ct);
return CreatedAtRoute("GetOrderById", new { id = order.Id }, order);
}
catch (OrderAlreadyExistsException ex)
{
// Return 409 Conflict wrapped in ProblemDetails
var problem = new ProblemDetails
{
Title = "Order Creation Conflict",
Detail = ex.Message,
Status = StatusCodes.Status409Conflict,
Instance = HttpContext.Request.Path
};
return Conflict(problem);
}
catch (Exception ex)
{
// Log server error server-side, return general 500
var problem = new ProblemDetails
{
Title = "Internal Server Error",
Detail = "An unexpected error occurred.",
Status = StatusCodes.Status500InternalServerError,
Instance = HttpContext.Request.Path
};
return StatusCode(StatusCodes.Status500InternalServerError, problem);
}
}
Here the method handles semantic validation errors (422), business logic conflicts (409), and server errors (500), all with clear ProblemDetails payloads.
Version Your API From Day One
Why version?
- Allows independent evolution of your API's contract.
- Maintains backward compatibility for existing consumers.
- Smooths migration paths and deprecations.
Integrate versioning via the Microsoft.AspNetCore.Mvc.Versioning package:
services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
});
Observability: Logging, Metrics, and Tracing
What to Log?
- Incoming requests: method, path, headers (e.g. auth), correlation ID.
- Response status codes annotated with ProblemDetails for errors.
- Validation failures with detailed reasons.
- Exception stack traces and details for internal errors.
- Latency (response times), request size, response size.
Structured Logging Example (Serilog)
{
"Timestamp": "2024-06-18T12:34:56Z",
"Level": "Error",
"Message": "Order creation failed due to duplicate Id",
"RequestId": "af1e2437-1234-4321-abcd-1234567890ab",
"HttpMethod": "POST",
"RequestPath": "/api/v1/orders",
"StatusCode": 409,
"ProblemDetails": {
"title": "Order Creation Conflict",
"detail": "Order with ID xyz123 already exists.",
"status": 409,
"instance": "/api/v1/orders"
},
"Exception": "OrderAlreadyExistsException: Order with ID xyz123 already exists."
}
RED Metrics (For API Endpoints)
| Metric | What It Measures | Target |
|---|---|---|
| Request Rate | Number of requests per second | Monitor for spikes/drops |
| Error Rate | Percentage of failed requests | < 1-2% typical threshold |
| Duration | Latency of requests (e.g., P95) | < 500ms for GET, < 1s for POST |
USE Metrics (For Underlying Resources)
| Metric | Description | Typical Alert Condition |
|---|---|---|
| Utilization | % CPU, memory, or IO in use | > 85% sustained |
| Saturation | Queue length, load | Growing queue length |
| Errors | Resource errors (timeouts) | Any anomalous error spikes |
Distributed Tracing with OpenTelemetry in ASP.NET Core
Add tracing instrumentation to capture request flows and dependencies with minimal code:
using OpenTelemetry.Trace;
builder.Services.AddOpenTelemetryTracing(tracerProviderBuilder =>
{
tracerProviderBuilder
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation()
.AddJaegerExporter();
});
This enables trace correlation across services and helps diagnose latencies, errors, and root causes in production.
API Design Trade-Offs Table
| Concern | Approach A: Strict RESTful Semantics | Approach B: Pragmatic Flexibility |
|---|---|---|
| HTTP Verb Usage | Map verbs strictly (GET=read, POST=create) | Mix verbs for convenience (e.g., POST for updates) |
| Error Codes | Use standard status codes + ProblemDetails | Use custom codes or error wrappers |
| Idempotency Enforcement | Enforce idempotency rigorously | Skip idempotency in favor of simplicity |
| Versioning | URI-based versioning | Header-based versioning |
| Partial Updates | Use PATCH for partial updates explicitly | Use POST with action suffixes |
| Validation Failures | Return 422 (Not 400) for semantic error | Return 400 for all client errors |
Deep Dive: Internal Mechanics of ASP.NET Core ProblemDetails Handling
While RFC 7807 provides a standardized shape for error responses, ASP.NET Core’s integration of ProblemDetails extends this with rich, configurable behavior that’s essential to understand for robust REST API design.
ProblemDetails Lifecycle in ASP.NET Core
-
Exception or Validation Failure Occurs: Within your controller or middleware, an exception is either thrown or validation fails (ModelState invalid).
-
Middleware and Filters Engage: ASP.NET Core has built-in exception handling middleware (
UseExceptionHandler) and validation filters that detect control flow anomalies. -
ProblemDetails Object Created:
- For validation issues,
ValidationProblemDetailsis created automatically with detailed errors. - For exceptions, by default, the
ProblemDetailsFactorycreates aProblemDetailsinstance based on the exception type and status code. - You can customize this behavior via
IProblemDetailsFactoryor middleware.
- For validation issues,
-
Content Negotiation and Serialization:
- ASP.NET Core serializes
ProblemDetailsto JSON or XML according to the request'sAcceptheader. - It injects default values for
typeandtitleif not supplied, aiding consistency.
- ASP.NET Core serializes
-
Response Sent to Client: The status code, typically matching the HTTP semantics (4xx or 5xx), accompanies the serialized
ProblemDetailspayload.
Extensibility and Customization Points
- Custom ProblemDetails Subclasses: Extend
ProblemDetailsto include application-specific fields, e.g., error codes, trace IDs.
public class CustomProblemDetails : ProblemDetails
{
public string ErrorCode { get; set; }
public string TraceId { get; set; }
}
- Custom Middleware for Enrichment:
public class ProblemDetailsEnrichmentMiddleware
{
private readonly RequestDelegate _next;
public ProblemDetailsEnrichmentMiddleware(RequestDelegate next) => _next = next;
public async Task InvokeAsync(HttpContext context)
{
await _next(context);
if (context.Response.ContentType?.Contains("application/problem+json") == true)
{
// You may add correlation IDs or environment debug flags here by re-reading response
}
}
}
What Happens Under the Hood? Simplified Flow
sequenceDiagram
participant Controller
participant ExceptionHandlerMiddleware
participant ProblemDetailsFactory
participant JSONSerializer
participant Client
Controller->>ExceptionHandlerMiddleware: Throw or Validation fail
ExceptionHandlerMiddleware->>ProblemDetailsFactory: Request ProblemDetails creation
ProblemDetailsFactory-->>ExceptionHandlerMiddleware: ProblemDetails instance
ExceptionHandlerMiddleware->>JSONSerializer: Serialize ProblemDetails
JSONSerializer-->>Client: Return structured error payloadFigure 3: Internal flow of error handling and ProblemDetails generation in ASP.NET Core.
Important Performance and Security Considerations
- Avoid leaking sensitive data in
detailor custom fields, especially in production. - Cache static
ProblemDetailselements liketypeURI templates to reduce allocations. - Ensure exceptions are logged centrally;
ProblemDetailspayloads should be descriptive but not verbose. - Test behavior under high load since exception handling is on the request critical path but usually a minority case.
Production Scenario: End-to-End Handling of a Conflict on Order Creation
Let’s trace a real-life, end-to-end scenario illustrating a typical conflict error (409 Conflict) handled with ProblemDetails in an ASP.NET Core REST API for order creation.
Scenario Setup
- Client attempts to create an order with a unique client-generated order number.
- The system ensures order numbers are unique.
- If a duplicate order number is detected, the service throws an
OrderAlreadyExistsException.
Step-by-Step Flow
- Client Request:
POST /api/v1/orders HTTP/1.1
Content-Type: application/json
{
"clientOrderNumber": "XYZ123",
"items": [...],
"totalAmount": 100.00
}
- Controller Action:
- Model binder validates JSON and ModelState.
- Controller calls
_service.CreateAsync(req, ct).
- Service Layer:
- Calls the repository to check for existing order number.
- Throws
OrderAlreadyExistsExceptionif found.
- Exception Handling Middleware:
- The controller catches this exception in a try-catch block (as per example).
- Converts it to ProblemDetails with 409 Conflict status.
- Client Receives Response:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://example.com/probs/order-conflict",
"title": "Order Creation Conflict",
"status": 409,
"detail": "Order with client order number 'XYZ123' already exists.",
"instance": "/api/v1/orders"
}
- Client-side Handling:
- Parses the ProblemDetails JSON.
- Possibly retries with a different order number or shows a user-friendly message.
sequenceDiagram
participant Client
participant Controller
participant Service
participant Repository
participant Middleware
Client->>Controller: POST /api/v1/orders
Controller->>Service: CreateAsync(req)
Service->>Repository: Check duplicate order number
Repository-->>Service: Duplicate found
Service-->>Controller: Throw OrderAlreadyExistsException
Controller->>Middleware: Catch exception, create ProblemDetails
Middleware-->>Client: 409 Conflict + ProblemDetails JSONFigure 4: Sequence showing handling of a duplicate order leading to a 409 Conflict.
Edge Cases and Failure Modes in REST API Error Handling
Robust APIs handle not just nominal cases but various edge scenarios gracefully. Consider the following common pitfalls and their mitigations:
| Edge Case | Description | Recommended Approach |
|---|---|---|
| Malformed input JSON | JSON parse errors or invalid JSON sent | Return 400 Bad Request with minimal ProblemDetails, avoid leaking parsing internals. |
| Model validation failure | Violations of data annotations or custom validation | Return 422 Unprocessable Entity with ValidationProblemDetails. |
| Request throttled / rate limited | Exceeding API quotas | Return 429 Too Many Requests with details on retry window via ProblemDetails. |
| Dependency failure | Downstream database or API is unavailable | Return 503 Service Unavailable, optionally with retry-after indication in ProblemDetails. |
| Unhandled exceptions | Unexpected runtime errors | Return 500 Internal Server Error with generic ProblemDetails, log details server-side. |
| Invalid HTTP methods | Request uses unsupported HTTP verb on endpoint | Return 405 Method Not Allowed with supported methods in Allow header. |
| Partial update concurrency | PATCH conflicts due to concurrent updates | Return 409 Conflict with description indicating concurrency problem. |
Example: Handling Request Throttling
return StatusCode(429, new ProblemDetails
{
Title = "Too Many Requests",
Status = 429,
Detail = "You have exceeded your request quota. Retry after 60 seconds.",
Instance = HttpContext.Request.Path
});
Observability Extension: Detailed Logging and Trace Correlation for Error Handling
Proper observability turns opaque failures into resolvable issues swiftly.
What to Log on ProblemDetails Responses?
- Correlation / Trace IDs: Use
HttpContext.TraceIdentifierfor request correlation. - HTTP details: method, URI, query params.
- Status code and ProblemDetails payload.
- Exception stack trace and message (for 5xx).
- Duration until error returned.
Structured Logging Example (C# Serilog Middleware Snippet)
app.Use(async (context, next) =>
{
var sw = Stopwatch.StartNew();
try
{
await next();
}
finally
{
sw.Stop();
var statusCode = context.Response.StatusCode;
if (statusCode >= 400)
{
var problemDetails = context.Items["ProblemDetails"] as ProblemDetails;
Log.Error("{Method} {Path} responded {StatusCode} in {ElapsedMilliseconds}ms; ProblemDetails: {@ProblemDetails}",
context.Request.Method,
context.Request.Path,
statusCode,
sw.ElapsedMilliseconds,
problemDetails);
}
}
});
Trace Propagation With OpenTelemetry
Correlate logs with distributed traces by injecting trace IDs from OpenTelemetry:
var traceId = Activity.Current?.TraceId.ToString() ?? "N/A";
Log.Information("Handling request {Method} {Path} TraceId: {TraceId}", method, path, traceId);
Recommended SLI/SLO Table for REST APIs
| SLI | Target | SLO / Alert Threshold |
|---|---|---|
| Successful request ratio | ≥ 99.9% successful 2xx responses | Alert if < 99.5% sustained over 5 min |
| Error rate (4xx/5xx) | < 1-2% errors | Alert on spike above baseline |
| Request Latency | P95 < 500 ms for GET, < 1s for POST | Alert if 95th percentile latency exceeds thresholds |
| Availability (service up) | 99.99% uptime | Page on service down alerts |
| Dependency errors | Minimal due to retries/fallback | Alert on increase in downstream failure |
Decision Checklist for REST API Error Handling and ProblemDetails Use
Before shipping or evolving your REST API error handling, validate these points:
- Are all client-facing errors (4xx) returned with appropriate ProblemDetails or subclasses?
- Are semantic (business rule) errors communicated via correct HTTP status codes (e.g., 409, 422)?
- Is internal server failure information sanitized to prevent leakage?
- Are error responses consistent in shape, enabling easy client parsing?
- Is API versioning in place to avoid breaking clients with error structure changes?
- Are PATCH idempotency and partial update semantics documented and tested?
- Is the error payload extended with correlation IDs or debugging fields where appropriate?
- Does logging capture sufficient context for errors with trace and correlation IDs?
- Is distributed tracing configured end-to-end to capture error spans and dependencies?
- Are SLIs defined for error rate and latency, with alerting thresholds calibrated?
- Is your implementation tested under edge conditions: malformed requests, race conditions, throttling, and downstream failures?
By mastering these internal mechanisms, scenarios, and failure modes, you ensure your REST APIs built with C# and ASP.NET Core are not only correct on the surface but robust, observable, and maintainable at scale. These insights separate junior coding from principled engineering.
Summary and Best Practices Checklist
- Use HTTP verbs according to standard semantics.
- Return HTTP status codes that precisely describe the outcome.
- Leverage
ProblemDetailsfor all 4xx/5xx error payloads. - Design your API versions from the start.
- Document your API responses with
[ProducesResponseType]attributes for OpenAPI. - Employ robust validation and return 422 on semantic validation errors.
- Instrument your APIs for observability with structured logs, RED/USE metrics, and distributed tracing.
- Test idempotency and error handling thoroughly.
- Avoid overloading verbs — embrace PATCH for partial modifications.
Additional Resources
- RFC 7807 - Problem Details for HTTP APIs
- Microsoft Docs: ASP.NET Core Web API
- OpenAPI Specification - ProducesResponseType
- OpenTelemetry for .NET
By understanding these principles and standards, you can confidently design and evolve REST APIs that clients find intuitive, debuggable, and resilient. This is a critical skill for any C# engineer working in cloud-native or microservices environments.