experience-usability.html

Developer-experience details that make the API easy to learn and consume.

117 rules experience: usability 108 inlined · 9 from the engine

Run this ruleset

Lint any matching artifact against this ruleset with the Spotlight CLI:

npm i -g @spotlight-rules/spotlight-cli
spotlight lint api.yaml \
  --ruleset https://apicommons.org/assets/rulesets/experience-usability.spotlight.yaml

Or load it into the browser validator, post it to the HTTP API, or wire it into a CI gate. 9 of these rules are the engine's built-ins (they come with spotlight:*); the other 108 are inlined in the file below.

Ruleset definition

Loading…

Rules in this ruleset (117)

Skill Body Length Agent Skill

Skill Description Length Agent Skill

Skill Description Single Line Agent Skill

Skill Name Max Length Agent Skill

API Property Require Go SDK APIs.json

API Property Require Java SDK APIs.json

API Property Require Node SDK APIs.json

API Property Require Python SDK APIs.json

API Property Require Sandbox APIs.json

API Property Require SDK APIs.json

API Property Require Signup APIs.json

API Property Require Support Email APIs.json

API Property Require Support Issues URL APIs.json

API Property Require Support Page APIs.json

API Require Base URL APIs.json

Schema Include API Plan APIs.json

Schema Include Developer Portal APIs.json

Schema Include Discussion Forum APIs.json

Schema Include Documentation APIs.json

Schema Include Examples APIs.json

Schema Include Feedback Email APIs.json

Schema Include Feedback Issues URL APIs.json

Schema Include Getting Started APIs.json

Schema Include Insomnia Collection APIs.json

Schema Include Mock Server APIs.json

Schema Include Postman Collection APIs.json

Schema Include Postman Public Workspace APIs.json

Schema Include Pricing APIs.json

Schema Include Production Environment APIs.json

Schema Include Questions Issues URL APIs.json

Schema Include Staging Environment APIs.json

Arazzo Step OperationPath Arazzo engine

Asyncapi 3 Server Not Example Com AsyncAPI engine

Asyncapi Operation OperationId AsyncAPI engine

Asyncapi Server Not Example Com AsyncAPI engine

Asyncapi Servers AsyncAPI engine

Document Require Instructions MCP

Channel Parameter Require Examples OpenAPI

Component Message Require Examples OpenAPI

Document Require Realistic Examples OpenAPI

Document Require Server Defined OpenAPI

Header Require Examples OpenAPI

Limit Nested Sub Resources OpenAPI

Limit Path Length OpenAPI

Limit Path Parameter OpenAPI

Message Examples Form Complete Mocks OpenAPI

Message Require Examples OpenAPI

OAS3 API Servers OpenAPI engine

OAS3 Server Not Example.com OpenAPI engine

Operation Collection Support Filtering OpenAPI

Operation Collection Support Sorting OpenAPI

Operation Collection Support Sparse Fieldsets OpenAPI

Operation Examples Form Complete Mocks OpenAPI

Operation Get Support If Modified Since OpenAPI

Operation Get Support If None Match OpenAPI

Operation OperationId OpenAPI engine

Operation OperationId Valid In URL OpenAPI engine

Operation Post Not For Retrieval OpenAPI

Operation Put Require Request Body OpenAPI

Operation Require ID OpenAPI

Operation Require Identifier OpenAPI

Operation Write Support If Match OpenAPI

Operation Write Support If Unmodified Since OpenAPI

Parameter Collection Limit Param Default OpenAPI

Parameter Filter Param Only On Get OpenAPI

Parameter No Hybrid And Root Filtering OpenAPI

Parameter No ID Query OpenAPI

Parameter Optional Include Examples OpenAPI

Parameter Query Must Be Optional OpenAPI

Parameter Require Examples OpenAPI

Parameter Required Require Examples OpenAPI

Parameter Sort Param Only On Get OpenAPI

Path CORS Support Options Preflight OpenAPI

Path Max Nesting Depth OpenAPI

Path Parameter Not Empty OpenAPI

Path Require Query Parameter OpenAPI

Request Body Must Use JSON Content Type OpenAPI

Request Content Require Examples OpenAPI

Request Delete No Body OpenAPI

Request Get No Body OpenAPI

Request Support Accept Encoding OpenAPI

Request Support Accept Language OpenAPI

Request Support Baggage OpenAPI

Request Support Correlation ID OpenAPI

Request Support Form Urlencoded Media Type OpenAPI

Request Support JSON Media Type OpenAPI

Request Support JSON Media Type 2 OpenAPI

Request Support Multipart Media Type OpenAPI

Request Support Text Plain Media Type OpenAPI

Request Support Tracestate OpenAPI

Request Support XML Media Type OpenAPI

Response 202 Location Header OpenAPI

Response 202 Retry After OpenAPI

Response Collection Support Paging OpenAPI

Response Content Require Examples OpenAPI

Response Default Content Language En Us OpenAPI

Response Get Cache Control OpenAPI

Response Get Document 304 Not Modified OpenAPI

Response Get ETag OpenAPI

Response Get Last Modified OpenAPI

Response Get Link Header OpenAPI

Response Get Vary OpenAPI

Response Include Hypermedia Links OpenAPI

Response Must Use JSON Content Type OpenAPI

Response Ratelimit Header OpenAPI

Response Ratelimit Policy OpenAPI

Response Return Correlation ID OpenAPI

Response Write Document 412 Precondition Failed OpenAPI

Response Write ETag OpenAPI

Schema Collection Require Pagination Params OpenAPI

Schema Property Require Examples OpenAPI

Server Must Not Specify Port OpenAPI

Document Require Currency Plans

Plan Require Description Plans

Plan Require Features Plans

Plan Require Interval Plans

Plan Require Price Plans

← All experience rulesets