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)
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 |
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 |
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. |