The OpenAPI Specification (OAS 3.0 & 3.1) serves as the definitive single source of truth for modern software architectures. When crafted with strict design principles, an OpenAPI specification powers interactive API portals, automated client SDK generation, mock servers, security scanners, and runtime contract enforcement.
1. Standardize Resource Paths with Lower Kebab-Case Nouns
URIs represent resources, not operations. Always use plural nouns and lower kebab-case for resource collections (e.g., /v1/user-accounts instead of /v1/getUserAccounts or /v1/userAccounts). HTTP verbs specify the execution intent.
| HTTP Verb | URI Pattern | Action Intent | Idempotent |
|---|---|---|---|
| GET | /v1/payment-intents | List payment intents with filtering | Yes |
| POST | /v1/payment-intents | Create a new payment intent | No |
| GET | /v1/payment-intents/{id} | Retrieve specific payment intent | Yes |
| PUT | /v1/payment-intents/{id} | Full replacement of payment intent | Yes |
| PATCH | /v1/payment-intents/{id} | Partial mutation of payment intent | No |
| DELETE | /v1/payment-intents/{id} | Soft or hard deletion of resource | Yes |
RESTful HTTP Verb and Path Matrix
2. Structure Component Schemas for Maximum Reusability
Avoid duplicate inline object declarations. Extract core domain entities into the components/schemas block and reference them using canonical $ref pointers. This reduces specification file size, eliminates maintenance drift, and guarantees model consistency.
components:
schemas:
UserAccount:
type: object
required:
- id
- email
- status
- createdAt
properties:
id:
type: string
format: uuid
example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
email:
type: string
format: email
example: user@example.com
status:
type: string
enum: [active, suspended, pending_verification]
example: active
createdAt:
type: string
format: date-time
example: '2026-09-26T12:00:00Z'
UserAccountListResponse:
type: object
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/UserAccount'
pagination:
$ref: '#/components/schemas/PaginationMetadata'3. Enforce RFC 7807 Problem Details for Error Handling
Never leave 4xx and 5xx responses unmodeled or represented as plain strings. Adopt RFC 7807 (Problem Details for HTTP APIs) to provide structured machine-readable error responses across all endpoints.
components:
schemas:
ProblemDetails:
type: object
required:
- type
- title
- status
- detail
- instance
properties:
type:
type: string
format: uri
example: https://api.example.com/errors/invalid-parameter
title:
type: string
example: Invalid Input Parameter
status:
type: integer
example: 400
detail:
type: string
example: The provided email parameter does not comply with RFC 5322.
instance:
type: string
example: /v1/users/req_923847293844. Model Polymorphism with oneOf, anyOf, and Discriminators
When an endpoint accepts or returns varying payload types (e.g. CreditCardPayment vs BankTransferPayment), use oneOf coupled with an explicit discriminator object. This enables code generators to produce strongly-typed class hierarchies.
PaymentMethod:
type: object
required:
- methodType
discriminator:
propertyName: methodType
mapping:
credit_card: '#/components/schemas/CreditCardPayment'
bank_transfer: '#/components/schemas/BankTransferPayment'
oneOf:
- $ref: '#/components/schemas/CreditCardPayment'
- $ref: '#/components/schemas/BankTransferPayment'5. Secure Specifications with Explicit Security Requirement Objects
Define global security requirements in securitySchemes and specify OAuth 2.0 scopes, Bearer JWT tokens, or API Keys per endpoint. Explicit security definitions allow automated gateway enforcement and security linting.
Validate Your OpenAPI Spec for Enterprise Quality
Run your OpenAPI 2.0, 3.0, or 3.1 file through APIForge's deterministic quality analyzer to highlight missing descriptions, invalid operationIds, and security flaws.