X (Twitter) · API Governance Rules

X (Twitter) API Rules

Spectral linting rules defining API design standards and conventions for X (Twitter).

53 Rules error 17 warn 18 info 18
View Rules File View on GitHub

Rule Categories

delete deprecated external get info no openapi operation parameter paths post request response schema security servers tags

Rules

error
info-title-required
API title must be present and non-empty.
$.info
warn
info-title-format
API title should follow the pattern "X API" or "X [Name] API".
$.info.title
error
info-description-required
API description must be present and meaningful.
$.info
warn
info-description-min-length
API description should be at least 50 characters.
$.info.description
error
info-version-required
API version must be specified.
$.info
warn
info-contact-required
Contact information should be provided.
$.info
info
info-license-required
License information should be provided.
$.info
error
openapi-version-3
OpenAPI version must be 3.0.x.
$
error
servers-defined
At least one server must be defined.
$
error
servers-https-only
Server URLs must use HTTPS.
$.servers[*].url
info
servers-description
Server entries should have descriptions.
$.servers[*]
info
servers-x-domain
Server URLs should use api.x.com or ads-api.x.com domains.
$.servers[*].url
warn
paths-version-prefix
Paths should start with a version prefix (e.g., /2/).
$.paths
error
paths-no-trailing-slash
Paths must not have trailing slashes.
$.paths
error
paths-no-query-strings
Paths must not contain query strings.
$.paths
info
paths-snake-case
Path segments should use snake_case (the dominant X API convention).
$.paths
warn
paths-path-params-snake-case
Path parameters should use snake_case.
$.paths
warn
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,patch,delete]
error
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,patch,delete]
error
operation-operationid-required
Every operation must have an operationId.
$.paths[*][get,post,put,patch,delete]
error
operation-operationid-unique
Operation IDs must be unique across the API.
$
warn
operation-operationid-camelcase
Operation IDs should use camelCase with verb prefixes (e.g., getTweets, createPost, deleteUser).
$.paths[*][get,post,put,patch,delete].operationId
warn
operation-tags-required
Every operation must have at least one tag.
$.paths[*][get,post,put,patch,delete]
warn
tags-defined
Global tags array should be defined.
$
info
tags-title-case
Tag names should use Title Case (e.g., "Direct Messages", "Community Notes").
$.tags[*].name
error
parameter-description-required
All parameters must have a description.
$.paths[*][get,post,put,patch,delete].parameters[*]
warn
parameter-snake-case
Parameter names should use snake_case (the dominant X API convention).
$.paths[*][get,post,put,patch,delete].parameters[*]
error
parameter-schema-type
Parameters must have a schema with a type defined.
$.paths[*][get,post,put,patch,delete].parameters[*].schema
info
parameter-pagination-max-results
Pagination limit parameters should be named max_results.
$.paths[*].get.parameters[?(@.in=='query')]
info
parameter-pagination-token
Pagination cursor parameters should use next_token or pagination_token.
$.paths[*].get.parameters[?(@.in=='query')]
info
parameter-expansions
Expansion parameters should be named expansions for including related objects.
$.paths[*].get.parameters[?(@.in=='query')]
warn
request-body-json-content
Request bodies should use application/json content type.
$.paths[*][post,put,patch].requestBody.content
error
response-success-required
Every operation must define a success response (2xx).
$.paths[*][get,post,put,patch,delete].responses
error
response-description-required
All responses must have a description.
$.paths[*][get,post,put,patch,delete].responses[*]
info
response-default-error
Operations should define a default error response for unexpected errors.
$.paths[*][get,post,put,patch,delete].responses
warn
response-success-json
Success responses should use application/json content type.
$.paths[*][get,post,put,patch].responses.200.content
warn
schema-names-pascalcase
Schema names should use PascalCase.
$.components.schemas
warn
schema-type-required
Schemas should have a type defined.
$.components.schemas[*]
info
schema-properties-snake-case
Schema properties should use snake_case (the dominant X API convention).
$.components.schemas[*].properties
info
schema-description-top-level
Top-level schemas should have a description.
$.components.schemas[*]
warn
security-schemes-defined
Security schemes should be defined in components.
$.components
info
security-bearer-token
A BearerToken security scheme should be defined for app-only auth.
$.components.securitySchemes
info
security-oauth2-user
An OAuth2UserToken security scheme should be defined for user context auth.
$.components.securitySchemes
warn
security-operation-defined
Every operation should define its security requirements.
$.paths[*][get,post,put,patch,delete]
error
get-no-request-body
GET operations must not have a request body.
$.paths[*].get
warn
delete-no-request-body
DELETE operations should not have a request body.
$.paths[*].delete
info
post-request-body
POST operations should have a request body.
$.paths[*].post
info
response-data-wrapper
Success responses should use a data wrapper object for consistency.
$.paths[*][get,post].responses.200.content.application/json.schema.properties
info
response-errors-array
Error responses should include an errors array.
$.components.schemas[?(@.properties.errors)]
info
parameter-fields-dot-notation
Field selection parameters should use dot notation (e.g., tweet.fields, user.fields, media.fields).
$.paths[*].get.parameters[?(@.name)]
error
no-empty-descriptions
Descriptions must not be empty strings.
$..description
info
external-docs-encouraged
External documentation link should be provided.
$
warn
deprecated-description
Deprecated operations should explain the deprecation in their description.
$.paths[*][get,post,put,patch,delete][?(@.deprecated==true)]