Skip to content

C# Interview Guide: REST API Design — HTTP Verbs, Status Codes, ProblemDetails

Q9 — REST API Design — HTTP Verbs, Status Codes, and ProblemDetails Level: Junior | Topic: Web API HTTP Verb Semantics GET: Read a resource or collection. Idempotent. Returns 200 OK or 404 Not Found. POST: Create a new r...

Ekanatha Reddy Urivakili13 min2,095 words

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 VerbIntended ActionIdempotent?Typical Success Status CodesCommon Error Status Codes
GETRead resource(s)Yes200 OK, 404 Not Found400 Bad Request (malformed URI)
POSTCreate new resourceNo201 Created + Location header422 Unprocessable Entity (validation), 409 Conflict (duplicate)
PUTFull replacement of resourceYes204 No Content or 200 OK404 Not Found, 422 Unprocessable Entity
PATCHPartial updateNo/few idempotent, depends on implementation204 No Content404 Not Found, 422 Unprocessable Entity
DELETERemove resourceYes204 No Content or 404 Not Found409 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 PropertyDescription
typeA URI reference to human-readable documentation for the error type (optional).
titleA short, human-readable summary of the problem type.
statusHTTP status code returned from the server.
detailA detailed explanation specific to this occurrence of the problem (optional).
instanceA 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
    end

Figure 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 OrderDto

Figure 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 ProblemDetails for 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)

MetricWhat It MeasuresTarget
Request RateNumber of requests per secondMonitor for spikes/drops
Error RatePercentage of failed requests< 1-2% typical threshold
DurationLatency of requests (e.g., P95)< 500ms for GET, < 1s for POST

USE Metrics (For Underlying Resources)

MetricDescriptionTypical Alert Condition
Utilization% CPU, memory, or IO in use> 85% sustained
SaturationQueue length, loadGrowing queue length
ErrorsResource 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

ConcernApproach A: Strict RESTful SemanticsApproach B: Pragmatic Flexibility
HTTP Verb UsageMap verbs strictly (GET=read, POST=create)Mix verbs for convenience (e.g., POST for updates)
Error CodesUse standard status codes + ProblemDetailsUse custom codes or error wrappers
Idempotency EnforcementEnforce idempotency rigorouslySkip idempotency in favor of simplicity
VersioningURI-based versioningHeader-based versioning
Partial UpdatesUse PATCH for partial updates explicitlyUse POST with action suffixes
Validation FailuresReturn 422 (Not 400) for semantic errorReturn 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

  1. Exception or Validation Failure Occurs: Within your controller or middleware, an exception is either thrown or validation fails (ModelState invalid).

  2. Middleware and Filters Engage: ASP.NET Core has built-in exception handling middleware (UseExceptionHandler) and validation filters that detect control flow anomalies.

  3. ProblemDetails Object Created:

    • For validation issues, ValidationProblemDetails is created automatically with detailed errors.
    • For exceptions, by default, the ProblemDetailsFactory creates a ProblemDetails instance based on the exception type and status code.
    • You can customize this behavior via IProblemDetailsFactory or middleware.
  4. Content Negotiation and Serialization:

    • ASP.NET Core serializes ProblemDetails to JSON or XML according to the request's Accept header.
    • It injects default values for type and title if not supplied, aiding consistency.
  5. Response Sent to Client: The status code, typically matching the HTTP semantics (4xx or 5xx), accompanies the serialized ProblemDetails payload.

Extensibility and Customization Points

  • Custom ProblemDetails Subclasses: Extend ProblemDetails to 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 payload

Figure 3: Internal flow of error handling and ProblemDetails generation in ASP.NET Core.

Important Performance and Security Considerations

  • Avoid leaking sensitive data in detail or custom fields, especially in production.
  • Cache static ProblemDetails elements like type URI templates to reduce allocations.
  • Ensure exceptions are logged centrally; ProblemDetails payloads 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

  1. Client Request:
POST /api/v1/orders HTTP/1.1
Content-Type: application/json
{
  "clientOrderNumber": "XYZ123",
  "items": [...],
  "totalAmount": 100.00
}
  1. Controller Action:
  • Model binder validates JSON and ModelState.
  • Controller calls _service.CreateAsync(req, ct).
  1. Service Layer:
  • Calls the repository to check for existing order number.
  • Throws OrderAlreadyExistsException if found.
  1. Exception Handling Middleware:
  • The controller catches this exception in a try-catch block (as per example).
  • Converts it to ProblemDetails with 409 Conflict status.
  1. 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"
}
  1. 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 JSON

Figure 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 CaseDescriptionRecommended Approach
Malformed input JSONJSON parse errors or invalid JSON sentReturn 400 Bad Request with minimal ProblemDetails, avoid leaking parsing internals.
Model validation failureViolations of data annotations or custom validationReturn 422 Unprocessable Entity with ValidationProblemDetails.
Request throttled / rate limitedExceeding API quotasReturn 429 Too Many Requests with details on retry window via ProblemDetails.
Dependency failureDownstream database or API is unavailableReturn 503 Service Unavailable, optionally with retry-after indication in ProblemDetails.
Unhandled exceptionsUnexpected runtime errorsReturn 500 Internal Server Error with generic ProblemDetails, log details server-side.
Invalid HTTP methodsRequest uses unsupported HTTP verb on endpointReturn 405 Method Not Allowed with supported methods in Allow header.
Partial update concurrencyPATCH conflicts due to concurrent updatesReturn 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.TraceIdentifier for 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);
SLITargetSLO / Alert Threshold
Successful request ratio≥ 99.9% successful 2xx responsesAlert if < 99.5% sustained over 5 min
Error rate (4xx/5xx)< 1-2% errorsAlert on spike above baseline
Request LatencyP95 < 500 ms for GET, < 1s for POSTAlert if 95th percentile latency exceeds thresholds
Availability (service up)99.99% uptimePage on service down alerts
Dependency errorsMinimal due to retries/fallbackAlert 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 ProblemDetails for 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


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.