forge-docs

0010. REST API Design Standards

Status: Accepted Date: 2025-12-10 Context: Standardize REST API endpoint design across all microservices for consistency and maintainability.

Context

The codebase had inconsistent REST API endpoint patterns across services:

This inconsistency made the API harder to understand, maintain, and extend. It also violated REST principles and industry best practices.

Decision

We will adopt RESTful API design standards based on RFC 7231, RESTful Web Services principles, and industry best practices. All endpoints across all services must follow these standards:

Core Principles

  1. Resource-Based URLs: Use nouns, not verbs. Resources represent entities, not actions.
    • ✅ /candidates, /resumes, /job-specs
    • ❌ /parse/resume, /admin/toggle
  2. Plural Nouns: Use plural nouns for resource collections.
    • ✅ /candidates, /resumes
    • ❌ /candidate, /resume
  3. HTTP Methods: Use HTTP methods to indicate actions.
    • GET: Retrieve resources (idempotent, safe)
    • POST: Create resources or perform actions (not idempotent)
    • PUT: Replace entire resource (idempotent)
    • PATCH: Partial update (idempotent)
    • DELETE: Remove resource (idempotent)
  4. Query Parameters for Filtering: Use query parameters for filtering, searching, and pagination.
    • ✅ GET /candidates?candidateId={id}
    • ❌ GET /candidate/{email}/candidates
  5. Path Parameters for Identification: Use path parameters for resource identification.
    • ✅ GET /candidates/{candidateId}
    • ❌ GET /candidates?candidateId={id} (for single resource)
  6. Consistent ID Usage: Use UUIDs consistently in path parameters. Use query parameters for filtering by other attributes.
    • ✅ GET /candidates?candidateId={uuid}
    • ❌ GET /candidate/{email}/candidates
  7. Proper Status Codes:
    • 200 OK - Success
    • 201 Created - Resource created successfully
    • 204 No Content - Success with no response body
    • 400 Bad Request - Validation errors
    • 401 Unauthorized - Authentication required
    • 404 Not Found - Resource not found
    • 422 Unprocessable Entity - Validation errors (more specific than 400)
    • 500 Internal Server Error - Server errors
  8. Security Best Practices:
    • Never put sensitive data in URL query parameters (use POST with body)
    • Use POST for token exchange and validation operations
    • ✅ POST /auth/tokens/exchange with token in body
    • ❌ GET /auth/token/exchange?token=xxx

Endpoint Structure Examples

Resource Creation

@POST
@Path("/resumes")
@Consumes(MediaType.MULTIPART_FORM_DATA)
public Response createResume(@RestForm String candidateId, @RestForm FileUpload resume) {
    // ... create logic
    return Response.status(Response.Status.CREATED).entity(result).build();
}

Resource Retrieval with Filtering

@GET
@Path("/actor")
public Response getActor(
    @QueryParam("actorId") String actorId) {
    // ... query logic
    return Response.ok(actors).build();
}

Resource Update

@PUT
@Path("/admin/features/{featureName}")
@Consumes(MediaType.APPLICATION_JSON)
public Response updateFeature(
    @PathParam("featureName") String featureName,
    Map<String, Object> request) {
    // ... update logic
    return Response.ok(result).build();
}

Special Cases

Authentication Endpoints: Authentication endpoints are an exception where action-based URLs are acceptable, as they represent authentication operations, not resource operations.

Consequences

Positive:

References