API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• skills/create-steering-documents/SKILL.md
• spec-process-guide/templates/design-template.md
• spec-process-guide/examples/complex-system-spec.md
• spec-process-guide/templates/tasks-template.md
• commands/create-steering-documents-standalone.md
• spec-process-guide/resources/standards.md
• spec-process-guide/examples/simple-feature-spec.md

API Endpoints are a fundamental component of the spec-driven development process, serving as the contract for how different parts of a system, or external clients, interact with backend services. The project's methodology emphasizes defining these endpoints during the Design Phase to ensure clarity, consistency, and alignment with requirements before implementation begins.

The API design is guided by steering documents, specifically api-design.md, which establishes project-wide standards for RESTful practices, data formats, and authentication. These guidelines are then applied within detailed Design Templates to specify each endpoint's behavior, request/response structure, and error handling. This structured approach ensures that all APIs are consistent, well-documented, and ready for implementation.

API Design Guidelines

The project mandates a set of core principles for API design, captured in the api-design.md steering document. These guidelines are intended to be used for backend and API projects to ensure consistency and adherence to best practices.

Sources: skills/create-steering-documents/SKILL.md:101-147, commands/create-steering-documents-standalone.md:129-175

RESTful API Standards

APIs must adhere to RESTful principles to ensure predictability and standard compliance.

• HTTP Methods: Use methods appropriately (e.g., GET, POST, PUT, DELETE, PATCH).
• URL Patterns: Follow resource-based URL patterns, such as /api/v1/users/{id}.
• Resource Naming: Use plural nouns for resource collections (e.g., /users).
• Status Codes: Implement proper HTTP status codes to indicate the outcome of a request.
• Versioning: Include the API version in the URL path (e.g., /api/v1/).

This diagram illustrates the standard resource-based URL pattern.

Request/Response Format

Consistency in data exchange formats is critical.

• Data Format: All request and response bodies must use JSON.
• Naming Convention: A consistent naming convention (e.g., camelCase or snake_case) should be followed.
• Pagination: Endpoints that return lists of resources must include pagination.
• Error Format: A standardized error response format must be used.

Below is the standard JSON structure for error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": ["Email is required", "Password too short"]
  }
}

Sources: skills/create-steering-documents/SKILL.md:113-126, commands/create-steering-documents-standalone.md:141-154

Authentication and Authorization

Security is enforced through standardized authentication and authorization mechanisms.

• Authentication: Use JWT tokens for stateless authentication.
• Access Control: Implement Role-Based Access Control (RBAC).
• Rate Limiting: Protect endpoints from abuse through rate limiting.

Sources: skills/create-steering-documents/SKILL.md:129-133, commands/create-steering-documents-standalone.md:157-160

Documentation

API documentation is a mandatory deliverable for any API development.

• Standard: Use OpenAPI/Swagger for API documentation.
• Content: Documentation must include request/response examples and all possible error responses.

Sources: skills/create-steering-documents/SKILL.md:136-139, commands/create-steering-documents-standalone.md:163-165

API Specification in Design Documents

The design-template.md provides a formal structure for defining API endpoints during the design phase. This ensures every endpoint is thoroughly specified before any code is written.

Sources: spec-process-guide/templates/design-template.md:116-150

Endpoint Definition

Each endpoint is defined with its method, path, and detailed request/response schemas.

Element	Description
Method	The HTTP method (e.g., POST, GET).
Path	The resource path (e.g., /api/v1/[resource]/{id}).
Parameters	Path or query parameters with descriptions.
Request	A JSON object showing the expected request body structure.
Response	A JSON object showing the successful response body structure.
Error Responses	A list of possible HTTP error statuses and the conditions under which they occur.

Sources: spec-process-guide/templates/design-template.md:118-150

Data Flow

The design document should also visualize the data flow for a typical API interaction using a sequence diagram.

This diagram shows the sequence of events for a user action that triggers an API call.

API Endpoints in Complex Systems

For complex, multi-service architectures, the design expands to include an API Gateway and event-driven communication patterns. The API Gateway serves as a single entry point for all clients.

Sources: spec-process-guide/examples/complex-system-spec.md:70-98

This diagram shows a high-level microservices architecture with an API Gateway.

In this model, the API Gateway is responsible for:

• Request routing to the appropriate microservice.
• Centralized authentication.
• Rate limiting and CORS.
• SSL termination.

Sources: spec-process-guide/examples/complex-system-spec.md:103-107

From Design to Implementation

Once the API design is approved, it is broken down into actionable implementation tasks in the tasks-template.md. The API layer is typically a distinct phase in the implementation plan.

This flowchart illustrates how API design is translated into implementation tasks.

A typical task for creating an API endpoint would look like this:

• Task: Implement [Resource] API endpoints
• Sub-tasks:
  • Create REST endpoints with proper HTTP methods.
  • Add request/response validation.
  • Implement authentication and authorization.
  • Write API integration tests.
• Requirements Reference: Link back to the specific requirements the endpoint fulfills.

Sources: skills/task-breakdown/SKILL.md:131-138, spec-process-guide/examples/simple-feature-spec.md:200-205

Summary

The project's methodology treats API endpoints as a first-class citizen of the development lifecycle. By enforcing standardized guidelines through steering documents, specifying behavior in detailed design templates, and breaking down implementation into structured tasks, the process ensures that all APIs are robust, consistent, secure, and well-documented. This systematic approach is crucial for building scalable and maintainable systems, especially in complex, multi-service environments.