diff --git a/README.md b/README.md index 2c1ceb8..108c780 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Your contributions and community engagement from external sources to SPS Commerc ## Definition -The majority of this definition directs and acts as a REST API style guide, with a focus on designing uniform interfaces and contracts. While it addresses certain expected behaviors where necessary, it is not intended as a comprehensive overview or guidance of all the tenants of REST-style APIs. You are still expected to understand the core tenants, including client-server, statelessness, cache-ability, layered systems, etc. The following reading may help you understand the philosophy behind the REST Architectural Style. If you are new to RESTful design, here are some good resources: +The majority of this definition directs and acts as a REST API style guide, with a focus on designing uniform interfaces and contracts. While it addresses certain expected behaviors where necessary, it is not intended as a comprehensive overview or guidance of all the tenets of REST-style APIs. You are still expected to understand the core tenets, including client-server, statelessness, cache-ability, layered systems, etc. The following reading may help you understand the philosophy behind the REST Architectural Style. If you are new to RESTful design, here are some good resources: - [REST on Wikipedia](https://en.wikipedia.org/wiki/Representational_state_transfer) - Overview of common definitions and core ideas behind REST. - [REST Dissertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) - The chapter on REST in Roy Fielding's dissertation on Network Architecture, "Architectural Styles and the Design of Network-based Software Architectures". diff --git a/standards/collections.md b/standards/collections.md index 1c37f3d..d1f635b 100644 --- a/standards/collections.md +++ b/standards/collections.md @@ -370,7 +370,7 @@ To limit or narrow down the results of a collection endpoint you may provide fil - Filtering query parameters **MUST** always be optionally applied as indicated by URL Structures that all query parameters are always optional. - The resource identifier in a collection **SHOULD NOT** be used to filter collection results, resource identifier should be in the URI. - Filtering **SHOULD** only occur on endpoints that are collections using the schema described above. -- Filtering attribute names may represent nested objects and **MUS**T use a period to represent each segment of the object path: `grandparent.parent.child`. +- Filtering attribute names may represent nested objects and **MUST** use a period to represent each segment of the object path: `grandparent.parent.child`. - Limit filter references to three levels of object hierarchy in accordance with `GET-based` HTTP Methods ([Request Response](request-response.md)). - Filtering **MUST** only be implemented on `GET-based` HTTP Methods via query parameters. - Filtering using `GET-based` requests with query parameters **SHOULD** be avoided if expected use cases or allowed usage resolves URL lengths beyond a reasonable size for the developer experience or approaching limits defined in [URL Structure](url-structure.md). @@ -409,7 +409,7 @@ To limit or narrow down the results of a collection endpoint you may provide fil - Filtering **MUST** be limited to equality checks of JSON attributes represented in the response payload. - Attributes not represented in the response payload **SHOULD NOT** be available for filtering. - Attribute names **MUST** follow standard naming and serialization patterns as defined elsewhere for their keys (see [Serialization](serialization.md)). -- Filtering capability and support **MUST** be documented within your API spec to clearly indicate how a consumer can filter your resource. Given that filtering support can drastically vary from endpoint to endpoint, incredible detail and clarity must be provided within the documentation of your API spec. +- Filtering capability and support **MUST** be documented within your API spec to clearly indicate how a consumer can filter your resource. Given that filtering support can drastically vary from endpoint to endpoint, incredible detail and clarity must be provided within the documentation of your API spec. ```warning Take into consideration the performance of your filtering capability. It may be undesirable to support certain filtering capabilities if it has a substantial impact on your API performance. diff --git a/standards/errors.md b/standards/errors.md index cf4956c..08071ea 100644 --- a/standards/errors.md +++ b/standards/errors.md @@ -12,7 +12,7 @@ Just like an HTML error page that shows a useful error message to a visitor, an - The error schema defined here **MUST NOT** be returned for a `2xx` series status code (including with the usage of the `207` multi-status code, which is restricted). - An error or validation response **MUST** follow the error object schema and **SHOULD** have response `Content-Type` of: `application/problem+json`. - An error or validation response **MUST** include a `requestId` attribute that is used to correlate requests. -- If the request includes a request identifier as a X-Request-ID header, it **MUST** be used as `requestId` value and `X-Request-ID` header should be carried over to the response. +- If the request includes a request identifier as an `X-Request-ID` header, it **MUST** be used as `requestId` value and `X-Request-ID` header should be carried over to the response. - If a more detailed context is necessary to describe a problem or multiple problems, it **MUST** include the context extension, indicating validation violation per each field or object (if applicable). - Optional attributes of the error schema that remain `null` **MUST** be excluded from the response payload during the serialization process. - Error messages **SHOULD** be descriptive and grammatically correct in single or multiple sentence format, so they can be surfaced by API clients without the need for modification. diff --git a/standards/request-response.md b/standards/request-response.md index c2effe3..7c37a91 100644 --- a/standards/request-response.md +++ b/standards/request-response.md @@ -45,13 +45,13 @@ When responding to API requests, the following status code ranges **MUST** be us | `5xx` | Server Error | The server was not able to execute the method due to a site outage or software defect. 5xx range status codes **SHOULD NOT** be used for validation or logical error handling. | ```note -"HTTP applications are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, applications **MUST** understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response **MUST NOT** be cached" ([RFC 2626](https://www.ietf.org/rfc/rfc2616.txt)). +"HTTP applications are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, applications **MUST** understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response **MUST NOT** be cached" ([RFC 2616](https://www.ietf.org/rfc/rfc2616.txt)). ``` - Success **MUST** be reported with a status code in the `2xx` range. - Reason phrases **MUST NOT** be modified or customized. The default reason phrases deliver an industry-standard experience for API consumers. Use the response payload as necessary to communicate further reasoning. - HTTP status codes in the `2xx` range **MUST** be returned only if the complete code execution path is successful. There is no such thing as partial success. - - Bulk request operations **MUST** return a 200 status code with a response body indicating failures as part of the payload for each processed entity, unless all processing failures due to a system issue, in which case its appropriate to issue standard `5xx` error message. + - Bulk request operations **MUST** return a 200 status code with a response body indicating failures as part of the payload for each processed entity, unless all processing failures due to a system issue, in which case it's appropriate to issue a standard `5xx` error message. - Failures **MUST** be reported in the `4xx` or `5xx` range. This is true for both system errors and application errors. - All status codes used in the `4xx` or `5xx` range **MUST** return standardized error responses as outlined under [Errors](errors.md). - A server returning a status code in the `2xx` range **MUST NOT** return any error models defined in [Errors](errors.md), or any HTTP status code, as part of the response body. @@ -105,7 +105,7 @@ When responding to API requests, the following status code ranges **MUST** be us - The data as part of the payload cannot be converted to the underlying data type. - The data or parameters is not in the expected data format. - The required field is not available. -- Simple data validation type of error.. +- Simple data validation type of error. **Example Usage**: Used to inform errors with accepting incoming requests that: - Incorrectly formatted @@ -624,7 +624,7 @@ The purpose of the `GET` method is to retrieve a resource. - HTTP `GET` Method **MUST NOT** accept a request body. - HTTP `GET` Method **MUST** return a response body. - - The response body **SHOULD NO**T produce a complex response that requires unreasonable hierarchy traversal. Beyond three levels of an object reference becomes unwieldy and **SHOULD** be avoided for API designs in favor of additional resources. + - The response body **SHOULD NOT** produce a complex response that requires unreasonable hierarchy traversal. Beyond three levels of an object reference becomes unwieldy and **SHOULD** be avoided for API designs in favor of additional resources. - HTTP `GET` Method **MUST NOT** modify the state of the API resources as it is for retrieval purposes only. - HTTP `GET` Method **MUST** be idempotent. - HTTP `GET` Method **MUST** return a `404` status code when a resource is not present by a specified identifier unless there is intent to expose a soft-delete status. @@ -659,7 +659,7 @@ The primary purpose of `POST` is to create a resource. It may also be used for n - HTTP `POST` Method that results in the successful creation of the resource: - **MUST** indicate so with a `201` status code. - **MUST** return a reference to the resource created either as a link or a resource identifier in the response body or Location header or both. - - may **OPTIONALLY** return the newly created entity as a whole reference if it is different or resolved in comparison to the request body, understanding that it may not contain an `ETag` or appropriate cache-control headers the same as a GET request.. + - may **OPTIONALLY** return the newly created entity as a whole reference if it is different or resolved in comparison to the request body, understanding that it may not contain an `ETag` or appropriate cache-control headers the same as a GET request. - HTTP `POST` Method **MUST** return a `200` status code when successful with non-RESTful-based actions (see Actions in [URL Structure](url-structure.md)). - HTTP `POST` Method response body, if returned, **MUST NOT** be a primitive, but rather a complex object with the identifier or other response information. - HTTP `POST` Method **MUST** indicate asynchronous acceptance of the request that is without resolution as a `202` status code. @@ -809,11 +809,11 @@ The primary purpose of `PATCH` is to update parts of an entity and not replace t - HTTP `PATCH` Method **MUST** only update parts or certain fields of an entity in compliance with JSON Merge Patch semantics. - Fields that are not intended to be updated **MUST** not be provided in the request body. - - Fields that are intended to be removed, **MUS**T be set to `NULL` in the request body. + - Fields that are intended to be removed, **MUST** be set to `NULL` in the request body. - Arrays that are provided in a `PATCH` request **MUST** replace the entire array on the destination field. - HTTP `PATCH` Method **MUST NOT** be used to create a new entity on a collection. - HTTP `PATCH` Method **SHOULD** return a `204` status code for any success responses, other than asynchronous acceptance with a `202` status code. -- HTTP `PATCH` Method **SHOULD** NOT return a response body that is an echo of the request body if they are the same. It is acceptable to return a similar resolved entity as a convenience from calling the GET method. +- HTTP `PATCH` Method **SHOULD NOT** return a response body that is an echo of the request body if they are the same. It is acceptable to return a similar resolved entity as a convenience from calling the GET method. - HTTP `PATCH` Method **SHOULD** return a `409` when a resource cannot be updated because it would result in an invalid, or be in opposition to any constraints, including any database or persistent storage constraints. - HTTP `PATCH` Method **SHOULD** be used when updating attributes of a resource collection. - HTTP `PATCH` Method **SHOULD** take advantage of the same `ETag` state validation, if required, for `PATCH` requests as described under HTTP `PUT` Method. diff --git a/standards/url-structure.md b/standards/url-structure.md index d296e87..8f8a022 100644 --- a/standards/url-structure.md +++ b/standards/url-structure.md @@ -79,7 +79,7 @@ The paths of your API **MUST** be structured using the concepts defined for reso - A resource **SHOULD NOT** include HTTP method names. - A resource **SHOULD NOT** dynamically change its response body schema or shape based on query parameters or other dynamic behavior. If you require a differently shaped body to be returned, consider - breaking it into different resource endpoints. - A resource **MUST** only contain lowercase ISO basic Latin alphabet characters, the numeric characters `0-9`, and a hyphen or dash character. -- A resource **SHOULD NOT** should not contain `api` as a prefix in or a part of the path. +- A resource **SHOULD NOT** contain `api` as a prefix in or a part of the path. - A resource **MUST** use normalized paths without empty path segments. - A resource **MUST** be addressable without a trailing slash on the URI (i.e. `/users`) and additionally **SHOULD** support a trailing slash as the same addressable resource (i.e. `/users/ == /users`). - Personally identifiable information and other sensitive data **MUST NOT** be used within the URL as it can be easily inadvertently exposed. This data should be transmitted via HTTP Header or Request Body (both of which are encrypted during transport).