Category: Response Design
Description
APIs should use consistent media types across all operations. If most endpoints use application/json, outliers using different types (like application/xml) should be flagged.
What It Checks
This rule analyzes media type usage across the entire API:
- Collects all request body media types
- Collects all 2XX response media types
- Identifies the dominant media type
- Flags operations that deviate significantly from the norm
The rule only triggers when there's a clear dominant type (used more than twice as often as the outlier).
Why It Matters
Consistent media types improve:
- Developer Experience: Predictable data formats across the API
- Client Implementation: Single serialization/deserialization logic
- Maintainability: Consistent handling throughout the codebase
- Documentation Clarity: Clear expectations for API consumers
Examples
Good
paths:
/users:
get:
responses:
'200':
content:
application/json:
schema:
type: array
post:
requestBody:
content:
application/json:
schema:
type: object
responses:
'201':
content:
application/json:
schema:
type: object
/orders:
get:
responses:
'200':
content:
application/json:
schema:
type: array
Bad
paths:
/users:
get:
responses:
'200':
content:
application/json:
schema:
type: array
/orders:
get:
responses:
'200':
content:
application/json:
schema:
type: array
/reports:
get:
responses:
'200':
content:
application/xml: # Inconsistent with JSON-dominant API
schema:
type: array
Exceptions
- APIs that intentionally support multiple formats uniformly
- File upload/download endpoints (multipart/form-data, application/octet-stream)
- Legitimate use cases for different formats (e.g., reports in CSV)
Configuration
This rule has no configuration options. It is either enabled or disabled.
Related Rules
- Rule 39: Content-Type Must Be Used - Content type requirements
- Rule 21: XML Alternative Representation - Multiple format support
- Rule 16: 406 Not Acceptable - Content negotiation