rest-openapi-spec-design

name	rest-openapi-spec-design
metadata	{"category":"APIs and Integration Design"}
description	Production-grade RESTful API design standards, OpenAPI 3.1 specification structuring, contract-first API development, versioning strategies, rate limiting, and schema validation.
compatibility	OpenAPI 3.0/3.1, Swagger UI, Redoc, Prism Mock Server, Node.js / Python / Go

RESTful API & OpenAPI 3.1 Specification Design

Overview

This skill provides comprehensive standards and operational patterns for designing contract-first RESTful APIs using the OpenAPI 3.1 Specification (OAS 3.1). It covers clean schema definitions, reusable $ref components, pagination, rate limiting headers, idempotency keys, error contracts (RFC 7807), and automated mock server validation.

---

1. Contract-First API Design Principles

1. Contract-First Workflow: Define the OpenAPI 3.1 schema before writing backend code. Validate requests and responses strictly against the OAS spec using middleware.
2. Resource-Oriented Nouns: Use plural nouns for resource endpoints (/v1/orders, /v1/users/{userId}/invoices). Avoid verbs in URI paths (use POST /v1/orders/{id}/cancel only for RPC-style actions when RESTful state update is unsuitable).
3. HTTP Method Semantics:
   • GET: Idempotent & safe resource retrieval.
   • POST: Non-idempotent resource creation or action execution.
   • PUT: Idempotent resource replacement (requires full body).
   • PATCH: Idempotent partial resource update (JSON Patch RFC 6902 or JSON Merge Patch RFC 7396).
   • DELETE: Idempotent resource removal.
4. Standardized Error Handling (RFC 7807): All API errors must return application/problem+json formatted responses containing type, title, status, detail, and instance.
5. API Versioning: Enforce explicit semantic versioning in the URL path (/v1/, /v2/) or content negotiation via custom Accept headers (Accept: application/vnd.company.v1+json).

---

2. API Architecture & Standard Headers

[ Client Application ]
       │
       │ 1. Request with Bearer Token & Idempotency-Key
       ▼
[ API Gateway / Reverse Proxy ] ──(Rate Limit Check: X-RateLimit-*)
       │
       │ 2. Validate Request against OpenAPI Spec
       ▼
[ Microservice Backend ] ──(RFC 7807 Problem Detail on Failure)

Standard Header	Direction	Purpose	Example Value
Authorization	Request	Bearer JWT / API Key authentication	Bearer eyJhbGciOiJKV1Qi...
Idempotency-Key	Request	Guarantee safe retry execution for POST actions	7b9e1d2c-8a4f-4e3b-9c2d-1a0e9f8c7b6a
X-RateLimit-Limit	Response	Max requests permitted in current window	1000
X-RateLimit-Remaining	Response	Remaining quota in active window	984
X-RateLimit-Reset	Response	UTC Epoch seconds when quota resets	1770000000
Content-Type	Both	Media type payload indicator	application/json / application/problem+json

---

3. Anti-Patterns & Common Errors

• Anti-Pattern: Status Code 200 OK with Internal Error Payload ({"success": false, "error": "Unauthorized"})
  • Risk: Breaks HTTP client retry logic, monitoring alerts, and API gateway routing.
  • Remediation: Return explicit HTTP status codes (401 Unauthorized, 403 Forbidden, 422 Unprocessable Entity).
• Anti-Pattern: Monolithic OpenAPI Files (10,000+ lines)
  • Risk: Impossible code reviews, high merge conflict frequency, poor tooling performance.
  • Remediation: Modularize schemas using multi-file $ref structures and aggregate via Redocly CLI or Swagger CLI (redocly bundle).
• Anti-Pattern: Unbounded List Responses
  • Risk: Database memory exhaustion, excessive network latency on large datasets.
  • Remediation: Enforce cursor-based or limit-offset pagination with mandatory default limit (limit=20, max_limit=100).

---

4. Production OpenAPI 3.1 & Validation Snippets

A. Modular OpenAPI 3.1 Specification (openapi.yaml)

openapi: 3.1.0
info:
  title: Enterprise Order Management API
  description: High-performance, contract-first API for order lifecycle processing.
  version: 1.2.0
  contact:
    name: API Engineering Team
    email: [e-mail]

servers:
  - url: https://api.enterprise.com/v1
    description: Production Environment
  - url: https://sandbox-api.enterprise.com/v1
    description: Staging / Sandbox Environment

paths:
  /orders:
    post:
      summary: Create a new order
      operationId: createOrder
      tags:
        - Orders
      security:
         
             
      
          
           
           
                   
          
             
             
      
         
        
          
            
               
      
        
             
          
            
                   
              
                 
                 
          
            
              
                 
        
           
        
           
        
           

  
    
          
       
      
         
      
         
             
      
          
           
           
          
             
             
      
        
             
          
            
              
                 
        
           


  
    
       
       
       

  
    
       
      
         
         
         
      
        
           
           
        
           
           [, , ]
        
           
           
          
             

    
       
      
         
         
         
      
        
           
           
        
           
           
        
           
           

    
       
      
         
         
         
         
         
      
        
           
           
        
           
           
        
           
           [, , , ]
        
           
        
           
           

    
       
      
         
         
         
         
      
        
           
           
        
           
        
           
        
           
        
           
           

  
    
          
      
        
          
             
    
           
      
        
          
             
    
             
      
        
          
             
    
          
      
        
          
             

---

B. Node.js Express Middleware Validation via OpenAPI Spec (server.js)

import express from 'express';
import * as OpenApiValidator from 'express-openapi-validator';
import path from 'path';

const app = express();
app.use(express.json());

// Enforce OpenAPI Request & Response Validation Middleware
app.use(
  OpenApiValidator.middleware({
    apiSpec: './openapi.yaml',
    validateRequests: true,
    validateResponses: true,
    ignorePaths: /^\/docs/
  })
);

// Router implementation matching OpenAPI operationId
app.post('/v1/orders', (req, res) => {
  const idempotencyKey = req.headers['idempotency-key'];
  const { customerId, items, currency } = req.body;

  const totalAmount = items.reduce((sum, item) => sum + (item.quantity * item.unitPrice), 0);

  const newOrder = {
    id: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    customerId,
    status: 'PENDING',
    : (totalAmount.()),
    :  ().()
  };

  res.(, );
   res.().(newOrder);
});


app.( {
   status = err. || ;
  res.(status).().({
    : ,
    : err. || ,
    : status,
    : err. ? .(err.) : err.,
    : req.
  });
});

app.(,  .());