REST Guidelines Ruleset

The REST Guidelines Ruleset of an OpenAPI Specification (OAS) document consists of 3 domains:

• REST Conventions (naming resources and representations)
• REST Style (HTTP methods, headers, query parameters, and status codes)
• REST Additional (errors, verbs, and authorization)

REST Conventions Rules

Learn more about the REST Conventions used to make the following rules.

name_id	description	severity	mitigation
resource-pas-camel-case-info	Resource names use lowerCamelCase.	warning	Please update resource names in PasCamelCase format for the items identified. Note that this is a variant of Reference
resource-pas-camel-case-error	Resource names use lowerCamelCase.	error	Please update resource names in PasCamelCase format for the items identified. Note that this is a variant of Reference
resource-lower-camel-case-info	Resource names use lowerCamelCase.	warning	Please update resource names for the items identified. Reference
resource-lower-camel-case-error	Resource names use lowerCamelCase.	error	Please update resource names for the items identified. Reference
oas2-application-json-charset-utf8-required	JSON representations should be declared using 'application/json' or 'application/json; charset=UTF-8' media types.	error	Please update content type for the items identified. Reference
oas3-application-json-charset-utf8-required	JSON representations should be declared using 'application/json' or 'application/json; charset=UTF-8' media types.	error	Please update content type for the items identified. Reference
oas2-collections-returned-as-arrays	Collections are returned as arrays encapsulated with a named field such as 'items'.	error	Please update response for the items identified. Reference
oas3-collections-returned-as-arrays	Collections are returned as arrays encapsulated with a named field such as 'items'.	error	Please update response for the items identified. Reference
oas2-field-names-pas-camel-case	Representation field names use lowerCamelCase.	error	Please update field names in PasCamelCase format for the items identified. Note that this is a variant of Reference
oas3-field-names-pas-camel-case	Representation field names use lowerCamelCase.	error	Please update field names in PasCamelCase format for the items identified. Note that this is a variant of Reference
oas2-field-names-camel-case	Representation field names use lowerCamelCase.	error	Please update field names for the items identified. [Reference](rest-conventions.md#representation-fields
oas3-field-names-camel-case	Representation field names use lowerCamelCase.	error	Please update field names for the items identified. Reference
oas2-no-boolean-string-enums	Representation fields use format-native true/false values for booleans.	error	Please update boolean fields for the items identified. Reference
oas3-no-boolean-string-enums	Representation fields use format-native true/false values for booleans.	error	Please update boolean fields for the items identified. Reference

REST Style Rules

Learn more about the REST Style used to make the following rules.

name_id	description	severity	mitigation
post-header	POST operations that create resources should include a Location header.	error	Please add location header for the items identified. Reference
post-header-location	POST operations that create resources should include a Location header.	error	Please add location header for the items identified. Reference
oas2-post-201-created	POST operations which create objects return 201 Created, with a full or reference-only representation.	error	Please update responses for the items identified. Reference
put-200-204-success	PUT operations return either '200 OK' with full representation or '204 No Content'.	error	Please update response for the items identified. Reference
delete-204-success	DELETE operations return '204 No Content' on success.	error	Please update the spec. Reference
patch-200-204-success	PATCH operations return either '200 OK' with full representation or '204 No Content'.	error	Please update response for the items identified. Reference
head-operations-match-headers-with-get	HEAD operations must return response headers identical to the corresponding GET.	error	Please update response headers for the items identified. Reference
oas2-head-operations-no-body	HEAD operations with a corresponding GET operation must return no body content.	error	Please update response body for the items identified. Reference
oas3-head-operations-no-body	HEAD operations with a corresponding GET operation must return no body content.	error	Please update response body for the items identified. Reference
oas2-request-header-date-correct-type	HTTP headers follow the syntax specified in the corresponding RFCs.	error	Please update headers for the items identified. Reference
oas2-request-header-date-correct-regex	HTTP headers follow the syntax specified in the corresponding RFCs.	error	Please update headers for the items identified. Reference
oas2-request-header-accept-language-enum	HTTP headers follow the syntax specified in the corresponding RFCs.	error	Please update headers for the items identified. Reference
date-response-header-requirement	All responses include a 'Date' header in the GMT timezone and RFC 5322 format.	error	Please add a date header for the items identified. Reference
date-response-header-format-pattern-requirement	All responses include a 'Date' header in the GMT timezone and RFC 5322 format.	warning	Please add a date header for the items identified. Reference
date-response-header-regex-check	All responses include a 'Date' header in the GMT timezone and RFC 5322 format.	warning	Please add a date header for the items identified. Reference
tracking-id-header-requirement	All responses must include a 'TrackingID' header.	error	Please add a TrackingID response header for the items identified. Reference
oas2-tracking-id-header-string-requirement	'TrackingID' header should be a string in order to accommodate a UUID.	warning	Please update TrackingID response header for the items identified. Reference
oas3-tracking-id-header-string-requirement	'TrackingID' header should be a string in order to accommodate a UUID.	warning	Please update TrackingID response header for the items identified. Reference
etag-header-match-required	In cases where ETag is supported, such resources should also support If-Match and If-None-Match request headers.	error	Please add If-Match and If-None-Match headers for the items identified. Reference
no-etag-cache-control-header-required	Where caching is not appropriate, operations must include a Cache-Control header (e.g. max-age=0, no-cache)	low	Please add a Cache-Control header for the items identified. Reference
oas2-order-parameter-asc-desc	Ordering collections is designed with an 'order' query parameter specifying 'asc' or 'desc'.	error	Please update order values for the items identified. Reference
sort-recommend-order	Consider using 'order' with 'sort' in this operation.	low	Please add order query for the items identified. Reference
oas3-order-parameter-asc-desc	Ordering collections is designed with an 'order' query parameter specifying 'asc' or 'desc'.	error	Please update order values for the items identified. Reference
respond-with-recommended-get-codes	My API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges	error	Please update response codes for the items identified. Reference
respond-with-recommended-post-codes	My API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges	error	Please update response codes for the items identified. Reference
respond-with-recommended-patch-codes	My API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges	error	Please update response codes for the items identified. Reference
respond-with-recommended-put-codes	My API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges	error	Please update response codes for the items identified. Reference
respond-with-recommended-delete-codes	My API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges	error	Please update response codes for the items identified. Reference
status-codes-in-2xx-4xx-5xx	API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges.	error	Please update responses for the items identified. Reference
status-codes-in-2xx-3xx-4xx-5xx	API responds with recommended HTTP status codes in the 2xx/3xx/4xx/5xx ranges.	error	Please update responses for the items identified. Reference

REST Additional Rules

Learn more about the REST Additional used to make the following rules.

name_id	description	severity	mitigation
oas2-error-message	Error representations include a useful human-readable message.	error	Please update error message for the items identified.
oas3-error-message	Error representations include a useful human-readable message.	error	Please update error message for the items identified.
error-response-identifier	Error representations include an identifier to help with troubleshooting.	warning	Please add an error identifier for the items identified.
no-crud-verbs	Standard CRUD lifecycle operations map to HTTP verbs; Functional resources are used when non-standard CRUD are needed.	error	Please update resource names for the items identified.
oas3-jwt-format	My API access tokens are passed via the HTTP 'Authorization' header, with a 'Bearer' prefix.	error	Please update authorization for the items identified.