diff --git a/README.md b/README.md index d93bde8..32a9ba3 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ If you want to contact adidas API Team regarding these guidelines, you can mail This project is intended to provide the guidelines for design & development of APIs at adidas. -Adidas is not responsible for the usage of this software for different purposes that the ones described in the use cases. +Adidas is not responsible for the usage of this software for different purposes than the ones described in the use cases. ## Last Review @@ -87,6 +87,6 @@ February 2025 adidas AG publishes this software and accompanied documentation (if any) subject to the terms of the MIT license with the aim of helping the community with our tools and libraries which we think can be also useful for other people. You will find a copy of the MIT license in the root folder of this package. All rights not explicitly granted to you under the MIT license remain the sole and exclusive property of adidas AG. -NOTICE: The software has been designed solely for the purpose of providing API design and development guidelines. The software is NOT designed, tested or verified for productive use whatsoever, nor or for any use related to high-risk environments, such as health care, highly or fully autonomous driving, power plants, or other critical infrastructures or services. +NOTICE: The software has been designed solely for the purpose of providing API design and development guidelines. The software is NOT designed, tested or verified for productive use whatsoever, nor for any use related to high-risk environments, such as health care, highly or fully autonomous driving, power plants, or other critical infrastructures or services. For further information open the [adidas terms and conditions](https://github.com/adidas/adidas-contribution-guidelines/wiki/Terms-and-conditions) page. diff --git a/general-guidelines/validating-api-descriptions.md b/general-guidelines/validating-api-descriptions.md index e377903..25e6743 100644 --- a/general-guidelines/validating-api-descriptions.md +++ b/general-guidelines/validating-api-descriptions.md @@ -30,7 +30,7 @@ docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint "/tmp/file.yaml" ## Using Spectral -Once installed Spectral, you can validate an OAS file (in YAML or JSON format) according to a given set of rules. Spectral has a predefined set of rules validating OpenAPI 2.x (Swagger) and OpenAPI 3.x files. +Once Spectral is installed, you can validate an OAS file (in YAML or JSON format) according to a given set of rules. Spectral has a predefined set of rules validating OpenAPI 2.x (Swagger) and OpenAPI 3.x files. Spectral comes with a CLI and can be run from your command line: diff --git a/rest-api-guidelines/evolution/versioning.md b/rest-api-guidelines/evolution/versioning.md index 3d4c4cd..9b2a1a5 100644 --- a/rest-api-guidelines/evolution/versioning.md +++ b/rest-api-guidelines/evolution/versioning.md @@ -29,9 +29,9 @@ Adding a new action to existing resource with identifier `/greeting` doesn't cha ## Backward-incompatible Changes -A change to _resource identifier_, _resource metadata_, _resource actions_ and _resource relations_ that can't follow the [Rules for Extending](../../general-guidelines/rules-for-extending.md) **MUST** result into a **new resource variant**. Existing resource variant **MUST** be preserved. +A change to _resource identifier_, _resource metadata_, _resource actions_ and _resource relations_ that can't follow the [Rules for Extending](../../general-guidelines/rules-for-extending.md) **MUST** result in a **new resource variant**. Existing resource variant **MUST** be preserved. -A change to _representation format_ **SHOULD NOT** result into a new resource variant. +A change to _representation format_ **SHOULD NOT** result in a new resource variant. #### Example diff --git a/rest-api-guidelines/execution/caching.md b/rest-api-guidelines/execution/caching.md index a2bd457..9dd441d 100644 --- a/rest-api-guidelines/execution/caching.md +++ b/rest-api-guidelines/execution/caching.md @@ -34,7 +34,7 @@ Clients **SHOULD** be capable of using `max-age` and `max-stale` headers to excl ### Common Cache-Control Scenarios -Most common scenarios for controlling the cache-ability of a response includes: +Most common scenarios for controlling the cache-ability of a response include: 1. Setting expiration and revalidation. 2. Disabling the caching of a response. Refer to the [Cache-Control Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for additional information. diff --git a/rest-api-guidelines/execution/long-running-tasks/callback.md b/rest-api-guidelines/execution/long-running-tasks/callback.md index eac81c4..af07ed0 100644 --- a/rest-api-guidelines/execution/long-running-tasks/callback.md +++ b/rest-api-guidelines/execution/long-running-tasks/callback.md @@ -14,7 +14,7 @@ If the chosen way is based on using callbacks, the response to such an asynchron ## Subscription -The subscriber enrolls to specfic notifications. The subscriber resource **MUST** provide the information about the callback URL. Any data needed to require the execution of a task **MUST** be included in the request body. +The subscriber enrolls to specific notifications. The subscriber resource **MUST** provide the information about the callback URL. Any data needed to require the execution of a task **MUST** be included in the request body. The subscription is created by using the HTTP POST Request Method. It **SHOULD** be designed as follows: diff --git a/rest-api-guidelines/execution/long-running-tasks/files-upload.md b/rest-api-guidelines/execution/long-running-tasks/files-upload.md index 1bb2755..d24c598 100644 --- a/rest-api-guidelines/execution/long-running-tasks/files-upload.md +++ b/rest-api-guidelines/execution/long-running-tasks/files-upload.md @@ -1,6 +1,6 @@ # Files Upload -The upload of files using a REST API endpoint is a common practice. It implies certain concerns taht have to be addressed in the design phase of the API. +The upload of files using a REST API endpoint is a common practice. It implies certain concerns that have to be addressed in the design phase of the API. The API Consumer performs a key role in this case. The MIME type in the Content-Type header of the request is an important factor for a successful operation. An operation that needs to upload binary files **SHOULD** uses a collection resource with the POST HTTP Request Method. When processing an existing resource the request message body **MUST** contain the right MIME type of the resources being processed. @@ -37,7 +37,7 @@ It is recommended to upload the file alone, with no other content in the request - PDF -> application/pdf etc. -It is also recommended to compress the file to be uploaded, then using these MIM types (examples): +It is also recommended to compress the file to be uploaded, then using these MIME types (examples): - gzip -> application/gzip - zip -> application/zip @@ -69,14 +69,14 @@ spring.http.multipart.max-request-size=128KB # the total request size for a mult ### Configure Properly all the Components -Load tests should give you metrics about the average latency of the operations. Use these metrics to calcuate the best value for the timeout settings in the upstream/backend service. +Load tests should give you metrics about the average latency of the operations. Use these metrics to calculate the best value for the timeout settings in the upstream/backend service. -The API Gateway timeout settings have to be considered for the expected timeout values, aligned with the values in the upstream/backend service. Al other components in the infrastructure **MUST** be considered for the calculation of the final metrics. +The API Gateway timeout settings have to be considered for the expected timeout values, aligned with the values in the upstream/backend service. All other components in the infrastructure **MUST** be considered for the calculation of the final metrics. git commit ``` -|API Consumer/Client Timeout| ---> |External Load Balancer| ---> |API Gateway Timeout| ---> |Internal Load Balancer| ---> |Upstream/Backend Service Tiemout| +|API Consumer/Client Timeout| ---> |External Load Balancer| ---> |API Gateway Timeout| ---> |Internal Load Balancer| ---> |Upstream/Backend Service Timeout| ``` -The approach based on too long timeout values is not acceptable. You **MUST** follow a fast-fail approach with a expected duration of the upload. If this time is exceeded a timeout error **SHOULD** be sent to the API Consumer. The maximum size limit **SHOULD** be consistent with the timeout value. +The approach based on too long timeout values is not acceptable. You **MUST** follow a fast-fail approach with an expected duration of the upload. If this time is exceeded a timeout error **SHOULD** be sent to the API Consumer. The maximum size limit **SHOULD** be consistent with the timeout value. > Please also consider the client and API Gateway Timeout settings. In this case the lack of retrieval of a response during a too long upload operation can trigger a timeout error. \ No newline at end of file diff --git a/rest-api-guidelines/guides/complete-api-development.md b/rest-api-guidelines/guides/complete-api-development.md index e54585b..110dc2c 100644 --- a/rest-api-guidelines/guides/complete-api-development.md +++ b/rest-api-guidelines/guides/complete-api-development.md @@ -22,9 +22,9 @@ 6. Follow the [adidas API guidelines](https://adidas.gitbook.io/api-guidelines/introduction/readme) 7. Verify the OAS file you have written passes the Spectral test. - 8. Make sure the OAS file passes all adidas SwaggerHub style guide checks. A red banned will be showed at the bottom of the editor if something is wrong with the OAS content. + 8. Make sure the OAS file passes all adidas SwaggerHub style guide checks. A red banner will be shown at the bottom of the editor if something is wrong with the OAS content. 9. Review the API Design - 10. Publish the version in Swagger Hub doing that inmmutable. + 10. Publish the version in Swagger Hub doing that immutable. 2. **Develop the API** 1. Check out OAS file from Swagger Hub @@ -79,7 +79,7 @@ > Ensure you have all the operational context information: - Type of application - Servers - - Detailed ownership information (Organiational unit, API Owner, Support contact, etc) + - Detailed ownership information (Organizational unit, API Owner, Support contact, etc) > Ensure you have all the Non-Functional Requirements for your API like: - Caching strategy detailed for each endpoint @@ -120,7 +120,7 @@ 1. Create a new version in Swagger Hub 2. Follow the adidas API Guidelines for [**changes and versioning**](https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/evolution/versioning) - 3. Share with your skateholders the new version allow them write comments to reach a new agrenment + 3. Share with your stakeholders the new version allow them write comments to reach a new agreement 4. Avoid break current version follow the [**rules**](https://adidas.gitbook.io/api-guidelines/general-guidelines/rules-for-extending) 5. After the API Design change is verified, reviewed and approved, continue with the "Develop the API" phase 6. Make sure the CI/CD pipeline is set to run Dredd test in the CI/CD with the new version diff --git a/rest-api-guidelines/message/error-reporting.md b/rest-api-guidelines/message/error-reporting.md index 5b327d6..cb72319 100644 --- a/rest-api-guidelines/message/error-reporting.md +++ b/rest-api-guidelines/message/error-reporting.md @@ -4,7 +4,7 @@ The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) \(Problem Problem Detail is intended for use with the HTTP status codes 4xx and 5xx. Problem Detail **MUST NOT** be used with 2xx status code responses. -At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. `title` value **SHOULD NOT** change from occurrence to occurence of the problem, except for purposes of localization (e.g., using proactive content negotiation) [read more](https://tools.ietf.org/html/rfc7807#section-3.1) +At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. `title` value **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation) [read more](https://tools.ietf.org/html/rfc7807#section-3.1) ### Example @@ -124,7 +124,7 @@ A Problem Detail response **MUST NOT** contain a program stack trace or server l ## Working with Problem Detail -An API description **MAY** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. +An API description **MAY** list all the error codes with which the API responds. The error responses **SHOULD** describe the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. ## External resources