SuperAPI AI Directory

api-specification

Coding & development

View repository

Updated 10-16 03:40

About this skill

API Specification Skill

Overview

This skill generates comprehensive API documentation and a machine-readable OpenAPI 3.0 specification. It translates functional requirements from the SRS and architectural decisions from the HLD into a complete, implementation-ready API contract. The skill can run after 01-high-level-design completes and operates in parallel with 02-low-level-design and 04-database-design.

When to Use

  • After 01-high-level-design has produced HLD.md in projects/<ProjectName>/<phase>/<document>/, which identifies system components and integration points.
  • When SRS_Draft.md Section 3.2 provides the functional requirements that map to API endpoints.
  • When the team needs a formal API contract before backend development begins.

Quick Reference

Attribute Value
Inputs projects/<ProjectName>/<phase>/<document>/SRS_Draft.md, projects/<ProjectName>/<phase>/<document>/HLD.md, projects/<ProjectName>/_context/tech_stack.md
Outputs projects/<ProjectName>/<phase>/<document>/API_Specification.md, projects/<ProjectName>/<phase>/<document>/openapi.yaml
Tone Technical, specification-grade, implementation-ready
Standards OpenAPI 3.0, IEEE 29148-2018, RFC 7231

Input Files

File Location Required Purpose
SRS_Draft.md projects/<ProjectName>/<phase>/<document>/SRS_Draft.md Yes Functional requirements, security, performance
HLD.md projects/<ProjectName>/<phase>/<document>/HLD.md Yes System components, integration points, data flow
tech_stack.md projects/<ProjectName>/_context/tech_stack.md Yes Technology choices, framework conventions

Output Files

File Location Description
API_Specification.md projects/<ProjectName>/<phase>/<document>/API_Specification.md Human-readable API reference with all sections
openapi.yaml projects/<ProjectName>/<phase>/<document>/openapi.yaml Machine-readable OpenAPI 3.0 specification

Core Instructions

Follow these eleven steps in order. Halt and notify the user if a required input file is missing.

Step 1: Read Context Files

Read SRS_Draft.md and HLD.md from projects/<ProjectName>/<phase>/<document>/, and tech_stack.md from projects/<ProjectName>/_context/. Log every file path read. If any required file is missing, halt execution and report the gap.

Step 2: Extract API Resources

Extract entities and operations from SRS Section 3.2 to identify API resources. Each entity that the system manages (e.g., User, Order, Product) becomes a resource. Each operation on that entity becomes an endpoint.

For public, partner, workflow-heavy, or long-lived APIs, load references/practical-api-architecture.md before locking the resource model. Apply its consumer contract, idempotency, lifecycle, error-code, and observability checks.

Step 3: Map CRUD to HTTP Methods

Map CRUD operations to HTTP methods following REST conventions: Create = POST, Read = GET, Update (full) = PUT, Update (partial) = PATCH, Delete = DELETE. Use HLD component boundaries to determine resource grouping and URL namespace.

Step 4: Define Authentication Scheme

Extract the authentication mechanism from SRS Section 3.5.3 (Security Requirements). Define the scheme as one of: JWT Bearer Token, Session Cookies, or API Key. Reference skills/dual-auth-rbac/ if the project uses role-based access control with multiple authentication strategies.

Step 5: Define Endpoint Details

For each endpoint, specify: path (RESTful URL), HTTP method, description, path parameters with data types, query parameters with defaults, request body schema (JSON with field types and constraints), response schema (JSON with field types), and HTTP status codes (200, 201, 400, 401, 403, 404, 422, 500).

Step 6: Define Error Response Format

Define a standardized error response format for all endpoints. Reference skills/api-error-handling/ for the canonical pattern:

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "details": []
  }
}

Every error status code shall return this structure.

Step 7: Define Rate Limiting

Extract performance constraints from SRS Section 3.3 (Performance Requirements). Define rate limits per endpoint tier: public endpoints, authenticated endpoints, and administrative endpoints. Specify the rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Step 8: Define Pagination

Define pagination strategy for all list endpoints: cursor-based or offset-based depending on data characteristics. Include standard parameters page, per_page and response envelope total, data[]. Reference skills/api-pagination/ if available.

Step 9: Apply Advanced API Patterns (Optional)

For APIs with operations beyond standard CRUD, apply patterns from references/advanced-api-patterns.md:

  • Long-Running Operations: If any endpoint processes >10 seconds, implement the LRO pattern from references/long-running-operations.md (POST returns 202 + operation resource)
  • Batch Operations: If bulk create/update/delete is needed, implement batch endpoints from references/batch-operations.md (POST /resources:batchCreate)
  • Custom Methods: For non-CRUD actions (cancel, approve, archive), use POST /resource:action pattern
  • Field Masks: For large resources, implement partial response via fields parameter

Source: API Design Patterns (JJ Geewax)

Step 10: Generate API_Specification.md

Write the human-readable specification to projects/<ProjectName>/<phase>/<document>/API_Specification.md with all sections defined in the Output Format below.

Step 11: Generate openapi.yaml

Generate a valid OpenAPI 3.0 document at projects/<ProjectName>/<phase>/<document>/openapi.yaml. The document shall include: openapi: "3.0.3", info block, servers block, paths with all endpoints, components/schemas with all request/response models, and components/securitySchemes with the authentication definition.

Output Format

The generated API_Specification.md shall follow this template structure:

# API Specification: [Project Name]

## Document Header
## 1. API Overview
### 1.1 Base URL and Versioning
### 1.2 Content Types
### 1.3 Common Headers
## 2. Authentication and Authorization
### 2.1 Authentication Scheme
### 2.2 Authorization Model
### 2.3 Token Lifecycle
## 3. Endpoint Reference
### 3.x [Resource Name]
#### 3.x.1 [METHOD] /api/v1/resource
## 4. Request and Response Schemas
### 4.1 Common Models
### 4.2 Resource-Specific Models
## 5. Error Response Format
### 5.1 Standard Error Envelope
### 5.2 Error Code Registry
## 6. Rate Limiting
## 7. Pagination
## 8. Versioning Strategy
## 9. CORS and Security Headers
## 10. Traceability Matrix

Section 10 (Traceability Matrix) shall map each endpoint to its originating SRS requirement ID and the HLD component that owns it.

Common Pitfalls

  1. Missing error codes: Every endpoint shall document all possible HTTP status codes, not just the success case.
  2. Unprotected routes: Every non-public endpoint shall specify its authentication and authorization requirements.
  3. Inconsistent naming: Use consistent casing (snake_case or camelCase) and pluralization across all endpoints and schema fields.
  4. No pagination on list endpoints: Every endpoint that returns a collection shall include pagination parameters and metadata.
  5. Missing request validation: Document required fields, data types, and constraints for every request body.

Verification Checklist

  • All required input files were read and logged.
  • Every entity in SRS Section 3.2 maps to at least one API resource with CRUD endpoints.
  • Every endpoint specifies authentication requirements, request/response schemas, and all applicable status codes.
  • The error response format is consistent across all endpoints.
  • List endpoints include pagination parameters and response metadata.
  • The openapi.yaml file is valid OpenAPI 3.0 and contains all endpoints defined in API_Specification.md.
  • For long-lived or side-effecting APIs, the specification includes a consumer contract matrix, idempotency map, stable error-code registry with retryability, versioning/deprecation policy, and contract-test obligations.

Integration

Direction Skill Relationship
Upstream 03-design-documentation/01-high-level-design Consumes HLD.md for component boundaries
Upstream 02-requirements-engineering Consumes SRS_Draft.md for functional requirements
Downstream Phase 04 (Development) API contract drives backend implementation
Downstream Phase 05 (Testing) Endpoint definitions drive API test cases
Reference skills/api-error-handling/ Canonical error response patterns
Reference skills/api-pagination/ Pagination strategy patterns
Reference skills/dual-auth-rbac/ Authentication and RBAC patterns
Reference references/practical-api-architecture.md Book-distilled API architecture, lifecycle, idempotency, and error-semantics checks

Standards

  • OpenAPI 3.0: The OpenAPI Specification defines a standard, language-agnostic interface to HTTP APIs. Governs the structure of openapi.yaml.
  • IEEE 29148-2018: Systems and software engineering -- Life cycle processes -- Requirements engineering. Ensures traceability from requirements to API endpoints.
  • RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. Defines HTTP method semantics and status code meanings.

Resources

  • logic.prompt -- executable prompt for automated API specification generation.
  • README.md -- quick-start guide for this skill.