# 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](rest-conventions.md) 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](rest-conventions.md#capitalization)| |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](rest-conventions.md#capitalization)| |resource-lower-camel-case-info |Resource names use lowerCamelCase. |warning |Please update resource names for the items identified. [Reference](rest-conventions.md#capitalization) | |resource-lower-camel-case-error |Resource names use lowerCamelCase. |error |Please update resource names for the items identified. [Reference](rest-conventions.md#capitalization) | |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](rest-conventions.md#encoding) | |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](rest-conventions.md#encoding) | |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](rest-conventions.md#returned-collections) | |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](rest-conventions.md#returned-collections) | |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](rest-conventions.md#representation-fields) | |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](rest-conventions.md#representation-fields) | |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](rest-conventions.md#representation-fields) | |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](rest-conventions.md#data-types) | |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-conventions.md#data-types) ## REST Style Rules Learn more about the [REST Style](rest-style.md) 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](rest-style.md#post) | |post-header-location |POST operations that create resources should include a Location header. |error |Please add location header for the items identified. [Reference](rest-style.md#post) | |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](rest-style.md#post) | |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](rest-style.md#put) | |delete-204-success |DELETE operations return '204 No Content' on success. |error |Please update the spec. [Reference](rest-style.md#delete) | |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](rest-style.md#patch) | |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](rest-style.md#head) | |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](rest-style.md#head) | |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](rest-style.md#head) | |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](rest-style.md#standard-request-headers) | |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](rest-style.md#standard-request-headers) | |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](rest-style.md#standard-request-headers) | |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](rest-style.md#standard-response-headers) | |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](rest-style.md#standard-response-headers) | |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](rest-style.md#standard-response-headers) | |tracking-id-header-requirement |All responses must include a 'TrackingID' header. |error |Please add a `TrackingID` response header for the items identified. [Reference](rest-style.md#trackingid-header) | |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](rest-style.md#trackingid-header) | |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](rest-style.md#trackingid-header) | |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](rest-style.md#cache-control-headers) | |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](rest-style.md#cache-control-headers) | |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](rest-style.md#sorting) | |sort-recommend-order |Consider using 'order' with 'sort' in this operation. |low |Please add `order` query for the items identified. [Reference](rest-style.md#sorting) |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](rest-style.md#sorting) | |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](rest-style.md#returning-http-status-codes) | |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](rest-style.md#returning-http-status-codes) | |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](rest-style.md#returning-http-status-codes) | |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](rest-style.md#returning-http-status-codes) | |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](rest-style.md#returning-http-status-codes) | |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](rest-style.md#returning-http-status-codes) | |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-style.md#returning-http-status-codes) | ## REST Additional Rules Learn more about the [REST Additional](rest-additional.md) 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. |