@@ -29,7 +29,7 @@ The general guidelines section discusses the core principles relevant to any kin
### How to read the Guidelines
These Guidelines are available for online reading at [GitBook](https://adidas.gitbook.io/api-guidelines/) its source can be found on [GitHub](https://github.com/adidas/api-guidelines).
These Guidelines are available for online reading at [GitBook](https://adidas.gitbook.io/api-guidelines/). The source code can be found on [GitHub](https://github.com/adidas/api-guidelines).
The CAPITALIZED words throughout these guidelines have a special meaning:
@@ -43,7 +43,7 @@ Refer to [RFC2119](https://www.ietf.org/rfc/rfc2119) for details.
### Validating your API Guidelines against OpenAPI Specification
In the `ruleset.md` file you can find a digest of API Guidelines rules which you can validating your API description documents with. If you are using OpenAPI Specification as the API description format you can also leverage the `.spectral.yaml` ruleset to automatically verify your specification compliance using [Spectral](github.com/stoplightio/spectral/).
In the `ruleset.md` file you can find a digest of API Guidelines rules which you can use to validate your API description documents. If you are using OpenAPI Specification as the API description format you can also leverage the `.spectral.yaml` ruleset to automatically verify your specification compliance using [Spectral](github.com/stoplightio/spectral/).
To install Spectral you will need Node.js and a package manager (npm or yarn).
@@ -6,4 +6,4 @@ The API first principle is an extension of design-first principle. Therefore, a
**API design** (e.g., description, schema) **is the master of truth, not the API implementation.**
API implementation **MUST** always be compliant to particular API design which represents the [contract](contract.md) between API, and it's consumer.
API implementation **MUST** always be compliant to a particular API design which represents the [contract](contract.md) between API, and it's consumer.
Approved API Design, represented by its API Description or schema, **MUST** represent the **contract** between API stakeholder, implementers, and consumers.
An approved API Design, represented by its API Description or schema, **MUST** represent the **contract** between API stakeholders, implementers, and consumers.
An update to the corresponding contract \(API Design\) **MUST** be implemented and approved before any change to an API **MUST**.
An update to the corresponding contract \(API Design\) **MUST** be implemented and approved before any change to an API is made.
That is, send the necessary minimum and be tolerant as possible while consuming another service \([tolerant reader](https://martinfowler.com/bliki/TolerantReader.html)\).
That is, send the necessary minimum and be as tolerant as possible while consuming another service \([tolerant reader](https://martinfowler.com/bliki/TolerantReader.html)\).
Every registered API MUST be assigned a unique Client ID and a Client Secret as a part of an HTTP header. The Client Secret MUST NOT be shared. DO NOT solely rely on a Client ID for authentication.
Every registered API **MUST** be assigned a unique Client ID and a Client Secret as a part of an HTTP header. The Client Secret **MUST NOT** be shared. **DO NOT** solely rely on a Client ID for authentication.
## Access Control
Not every user has a right to every web service. This is vital, as you don't want administrative web services to be misused. The API key SHOULD be sent along as a cookie, body parameter, or HTTP message header to ensure that privileged collections or actions are properly protected from unauthorized use. Every API MUST BE authenticated before it can be used.
Not every user has a right to every web service. This is vital, as you don't want administrative web services to be misused. The API key **SHOULD** be sent along as a cookie, body parameter, or HTTP message header to ensure that privileged collections or actions are properly protected from unauthorized use. Every API **MUST BE** authenticated before it can be used.
## Masking HTTP Headers
Server versioning information or any other sensitive information from the HTTP headers SHOULD BE removed/masked according to industry best practices. This prevents any form of targeted attacks since the vulnerabilities are mostly specific to the vendors.
Server versioning information or any other sensitive information from the HTTP headers **SHOULD BE** removed/masked according to industry best practices. This prevents any form of targeted attacks since the vulnerabilities are mostly specific to the vendors.
## Use Security HTTP Headers
Modern browsers support many HTTP headers that can improve web application security to protect against clickjacking, cross-site scripting, and other common attacks.
Your API SHOULD use security HTTP headers to improve the level of protection.
See the [list of OWASP Secure Headers](https://owasp.org/www-project-secure-headers/) to form the combination of headers
Ideally you SHOULD inlcude HTTP Security Headers at least in these areas unless there is an incompatibility with some functional requirement:
Your API **SHOULD** use security HTTP headers to improve the level of protection.
See the [list of OWASP Secure Headers](https://owasp.org/www-project-secure-headers/) to form the combination of headers.
Ideally you **SHOULD** inlcude HTTP Security Headers at least in these areas unless there is an incompatibility with some functional requirement:
- HTTP Strict Transport Security
- Content-Security-Policy
@@ -30,7 +30,7 @@ Ideally you SHOULD inlcude HTTP Security Headers at least in these areas unless
## Session Management
RESTful web services SHOULD use session-based authentication, either by establishing a session token via a POST or by using an API key \(Client ID and a Client Secret\) as a POST body argument or as a cookie. Usernames, passwords, session tokens, API keys, and sensitive information MUST NOT appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.
RESTful web services **SHOULD** use session-based authentication, either by establishing a session token via a POST or by using an API key \(Client ID and a Client Secret\) as a POST body argument or as a cookie. Usernames, passwords, session tokens, API keys, and sensitive information **MUST NOT** appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.
## Protect HTTP Methods
@@ -38,7 +38,7 @@ RESTful API often use GET \(read\), POST \(create\), PUT \(replace/update\) and
## HTTP Status Codes
While designing a REST API, DON'T just use 200 for success or 404 for error. Every error message needs to be customized as NOT to reveal any unnecessary information. Here are some guidelines to consider for each REST API status return code. Proper error handle may help to validate the incoming requests and better identify the potential security risks.
While designing a REST API, **DO NOT** just use 200 for success or 404 for error. Every error message needs to be customized as NOT to reveal any unnecessary information. Here are some guidelines to consider for each REST API status return code. Proper error handle may help to validate the incoming requests and better identify the potential security risks.
* 200 OK - Response to a successful REST API action.
* 400 Bad Request - The request is malformed, such as message body format error.
@@ -54,17 +54,17 @@ Everything you know about [input validation](https://www.owasp.org/index.php/Dat
* Secure parsing: Use a secure parser for parsing the incoming messages. If you are using XML, make sure to use a parser that is NOT VULNERABLE to XXE and similar attacks.
* Strong typing: It's difficult to perform most attacks if the only allowed values are true or false, or a number, or one of a small number of acceptable values. Strongly type incoming data as quickly as possible.
* Validate incoming content-types: When POSTing or PUTting new data, the client will specify the Content-Type \(e.g. application/xml or application/json\) of the incoming data. The server SHOULD NEVER assume the Content-Type; it SHOULD ALWAYS check that the Content-Type header and the content are the same types. A lack of Content-Type header or an unexpected Content-Type header SHOULD result in the server rejecting the content with a 406 Not Acceptable response.
* Validate response types: It is common for REST services to allow multiple response types \(e.g. application/xml or application/json, and the client specifies the preferred order of response types by the Accept header in the request. DO NOT simply copy the Accept header to the Content-type header of the response. Reject the request \(ideally with a 406 Not Acceptable response\) if the Accept header does not specifically contain one of the allowable types. Because there are many MIME types for the typical response types, it's important to document for clients specifically which MIME types should be used.
* XML input validation: XML-based services MUST ensure that they are protected against common XML-based attacks by using secure XML-parsing. This typically means protecting against XML External Entity attacks, XML-signature wrapping etc.
* Validate incoming content-types: When POSTing or PUTting new data, the client will specify the Content-Type \(e.g. application/xml or application/json\) of the incoming data. The server **SHOULD NEVER** assume the Content-Type; it **SHOULD ALWAYS** check that the Content-Type header and the content are the same types. A lack of Content-Type header or an unexpected Content-Type header **SHOULD** result in the server rejecting the content with a 406 Not Acceptable response.
* Validate response types: It is common for REST services to allow multiple response types \(e.g. application/xml or application/json, and the client specifies the preferred order of response types by the Accept header in the request. **DO NOT** simply copy the Accept header to the Content-type header of the response. Reject the request \(ideally with a 406 Not Acceptable response\) if the Accept header does not specifically contain one of the allowable types. Because there are many MIME types for the typical response types, it's important to document for clients specifically which MIME types should be used.
* XML input validation: XML-based services **MUST** ensure that they are protected against common XML-based attacks by using secure XML-parsing. This typically means protecting against XML External Entity attacks, XML-signature wrapping etc.
## Escape Content
This means removing any executable code that would cause the browser to do something you don’t want it to. Typically this means removing `// < for more information on how to implement CSRF-protection.
CSRF is easily achieved even using random tokens if any XSS exists within your application, so PLEASE MAKE SURE you understand [how to prevent XSS](https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet).
CSRF is easily achieved even when using random tokens if any XSS exists within your application, so **PLEASE MAKE SURE** you understand [how to prevent XSS](https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet).
## Insecure direct object references
A URL or even a POSTed form should NEVER contain an access control "key" or similar that provides automatic verification. A contextual data check needs to be done, server side, with each request.
A URL or even a POSTed form **SHOULD NEVER** contain an access control "key" or similar that provides automatic verification. A contextual data check needs to be done, server side, with each request.
## Enable CORS for all APIs
When your API's resources receive requests from a domain other than the API's domain, you MUST enable cross-origin resource sharing \(CORS\) for selected methods on the resource. This amounts to having your API respond to the OPTIONS preflight request with at least the following CORS-required response headers:
When your API's resources receive requests from a domain other than the API's domain, you **MUST** enable cross-origin resource sharing \(CORS\) for selected methods on the resource. This amounts to having your API respond to the OPTIONS preflight request with at least the following CORS-required response headers:
* Access-Control-Allow-Methods
* Access-Control-Allow-Headers
@@ -98,32 +98,32 @@ When your API's resources receive requests from a domain other than the API's do
## Data in transit
Unless the public information is entirely read-only, the use of TLS v1.2 should be MANDATED, especially when credentials, updates, deletions, and any value transactions are performed. The overhead of TLS is negligible on modern hardware, with a minor latency increase that is more than compensated by safety for the end user.
Unless the public information is entirely read-only, the use of TLS v1.2 should be **MANDATED**, especially when credentials, updates, deletions, and any value transactions are performed. The overhead of TLS is negligible on modern hardware, with a minor latency increase that is more than compensated by safety for the end user.
## Message Integrity
In addition to HTTPS/TLS, JSON Web Token \(JWT\) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWT can not only be used to ensure the message integrity but also authentication of both message sender/receiver. The JWT includes the digital signature hash value of the message body to ensure the message integrity during the transmission.
In addition to HTTPS/TLS, JSON Web Token \(JWT\) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWT can be used not only to ensure the message integrity but also authentication of both message sender/receiver. The JWT includes the digital signature hash value of the message body to ensure message integrity during the transmission.
## Weak SSL/TLS Ciphers Support:
The encryption ciphers supported by the server may allow an attacker to eavesdrop on the connection. Verify the following guidelines:
* When serving up content to your users, ONLY strong ciphers are enabled \(128 bits and above\).
* When connecting to other remote systems ensure that your client DOES NOT connect using a weak cipher if the server supports it.
* Renegotiation MUST be properly configured \(e.g. Insecure Renegotiation MUST be disabled, due to MiTM attacks and Client-initiated Renegotiation MUST be disabled, due to Denial of Service vulnerability\).
* MD5 MUST NOT be used, due to known collision attacks.
* RC4 MUST NOT be used, due to cryptoanalytical attacks
* Server SHOULD be protected from BEAST Attack
* Server SHOULD be protected from CRIME attack, TLS compression MUST be disabled
* Server SHOULD support Forward Secrecy
* When serving up content to your users, **ONLY** strong ciphers are enabled \(128 bits and above\).
* When connecting to other remote systems ensure that your client **DOES NOT** connect using a weak cipher if the server supports it.
* Renegotiation **MUST** be properly configured \(e.g. Insecure Renegotiation **MUST** be disabled, due to Man in the Middle (MiTM) attacks and Client-initiated Renegotiation **MUST** be disabled, due to Denial of Service vulnerability\).
* MD5 **MUST NOT** be used, due to known collision attacks.
* RC4 **MUST NOT** be used, due to cryptoanalytical attacks
* Server **SHOULD** be protected from BEAST Attack
* Server **SHOULD** be protected from CRIME attack, TLS compression **MUST** be disabled
* Server **SHOULD** support Forward Secrecy
## Mixed Content
When serving up content to your users over SSL, it’s important that you DO NOT include content served over HTTP such as Images, JavaScript, Flash, or CSS. By mixing HTTP content with HTTPS content, you expose your users to maninthe middle attacks and eliminate the security benefits that SSL/TLS provides.
When serving up content to your users over SSL, it’s important that you **DO NOT** include content served over HTTP such as Images, JavaScript, Flash, or CSS. By mixing HTTP content with HTTPS content, you expose your users to Man-in-the-Middle attacks and eliminate the security benefits that SSL/TLS provides.
## SSL Certificate Validity – client and server
For the communication to be set up, a number of checks on the certificates MUST be passed:
For the communication to be set up, a number of checks on the certificates **MUST** be passed:
* Checking if the Certificate Authority \(CA\) is a known one \(meaning one considered trusted\);
* Checking that the certificate is currently valid;
@@ -131,15 +131,15 @@ For the communication to be set up, a number of checks on the certificates MUST
## Certificate Requirements
The following checklist NEEDS TO BE followed while using an SSL certificate:
The following checklist **MUST** be followed while using an SSL certificate:
* X.509 certificates key length MUST be strong \(e.g. if RSA or DSA is used the key MUST be at least 1024 bits\).
* X.509 certificates MUST be signed only with secure hashing algorithms \(e.g. not signed using the MD5 hash, due to known collision attacks on this hash\).
* Fully Qualified Domain Name \(FQDN\) certificates is a MANDATE. This is a certificate that has been issued with a name registered with an entity that manages a top-level domain \(TLD\). The differentiating characteristic about an FQDN is that it is unique. There is one controller and that controller determines who can have any name under that root.
* NO USAGE of Wildcard SSL Certificate.
* SHA-1 \(or MD5\) certificates SHOULD NOT BE used. The problem isn't the security of the server's real certificate; it's the client policy that allows the client to trust low-security certificates.
* X.509 certificates key length **MUST** be strong \(e.g. if RSA or DSA is used the key MUST be at least 1024 bits\).
* X.509 certificates **MUST** be signed only with secure hashing algorithms \(e.g. not signed using the MD5 hash, due to known collision attacks on this hash\).
* Fully Qualified Domain Name \(FQDN\) certificates is a **MANDATE**. This is a certificate that has been issued with a name registered with an entity that manages a top-level domain \(TLD\). The differentiating characteristic about an FQDN is that it is unique. There is one controller and that controller determines who can have any name under that root.
***NO USAGE** of Wildcard SSL Certificate.
* SHA-1 \(or MD5\) certificates **SHOULD NOT BE** used. The problem isn't the security of the server's real certificate; it's the client policy that allows the client to trust low-security certificates.
## Penetration Testing
An exhaustive penetration testing needs to be performed against all the developed APIs exposed to the public internet and within adidas internal network. For detailed understanding of the process, please contact the adidas Global IT Security Team.
An exhaustive penetration testing **MUST** be performed against all the developed APIs exposed to the public internet and within adidas internal network. For detailed understanding of the process, please contact the adidas Global IT Security Team.
Every API design **SHOULD** be stored in a Version Control System \(Bitbucket, GitHub\). Where possible the API design **SHOULD** stored in the **same** repository as the API implementation.
Every API design **SHOULD** be stored in a Version Control System \(e.g., Bitbucket, GitHub\). Where possible the API design **SHOULD** be stored in the **same** repository as the API implementation.
The design of application data model **MUST** consider the application use cases, as well as the upstream and downstream systems, use cases.
The design of application data model **MUST** consider the application use cases, as well as the upstream and downstream systems use cases.
The design of the data model of an application **MUST** consider the [adidas Corporate Data Model](https://collaboration.adidas-group.com/sites/CS-GDM/Corporate%20Data%20Dictionary/Data%20Dictionary.htm) \(internal link\).
This section includes the recommended approaches to handling long running tasks (LRTs) in REST APIs.
You can identify a LRT quite easily. The main factor to consider are the metrics from latency of the endpoint. If it requiress tens of seconds even minutes we are facing a problem related to LRTs.
You can identify a LRT quite easily. The main factor to consider are the metrics from latency of the endpoint. If it requiress tens of seconds or even minutes we are facing a problem related to LRTs.
LRTs cannot be handled in a regular straight synchronous call. The amount of commited recources at the network, client and server levels are huge when connections are blocked for several minutes.
If an API operation can be considered as a long running task and the API Consumer can track its progress, the response to the LRT **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
If an API operation can be considered as a long running task (LRT) and the API Consumer can track its progress, the response to the LRT **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
## Task Tracking Resource
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Cesareo
GitHub