GitBook: [master] 69 pages modified

SUMMARY.md

@@ -22,40 +22,38 @@
   * [API Design Platform](rest-api-guidelines/core-principles/apiary.md)
   * [Design Maturity](rest-api-guidelines/core-principles/design-maturity.md)
   * [Testing](rest-api-guidelines/core-principles/testing.md)
-* [Functionality](rest-api-guidelines/functionality/README.md)
-  * [Protocol](rest-api-guidelines/functionality/protocol/README.md)
-    * [HTTP](rest-api-guidelines/functionality/protocol/http.md)
-    * [TLS](rest-api-guidelines/functionality/protocol/tls.md)
-    * [Separate Concerns](rest-api-guidelines/functionality/protocol/separate-concerns.md)
-    * [Request Methods](rest-api-guidelines/functionality/protocol/use-appropriate-methods.md)
-    * [Status Codes](rest-api-guidelines/functionality/protocol/use-appropriate-status-codes.md)
-  * [Message](rest-api-guidelines/functionality/message/README.md)
-    * [Message Formats](rest-api-guidelines/functionality/message/message-formats.md)
-    * [Content Negotiation](rest-api-guidelines/functionality/message/content-negotiation.md)
-    * [HAL](rest-api-guidelines/functionality/message/hal.md)
-    * [Problem Detail](rest-api-guidelines/functionality/message/error-reporting.md)
-    * [Foreign Key Relations](rest-api-guidelines/functionality/message/foreign-key-relations.md)
-  * [Application](rest-api-guidelines/functionality/application/README.md)
-    * [Corporate Data Model](rest-api-guidelines/functionality/application/harmonize-data.md)
-    * [Common Data Types](rest-api-guidelines/functionality/application/common-data-types.md)
-* [Quality](rest-api-guidelines/quality/README.md)
-  * [Execution](rest-api-guidelines/quality/execution/README.md)
-    * [Pagination](rest-api-guidelines/quality/execution/pagination.md)
-    * [Asynchronous Tasks](rest-api-guidelines/quality/execution/asynchronous-tasks.md)
-    * [Batch Operations](rest-api-guidelines/quality/execution/batch-operations.md)
-    * [Search Requests](rest-api-guidelines/quality/execution/search-requests.md)
-    * [Query Requests with Large Inputs](rest-api-guidelines/quality/execution/query-requests-with-large-inputs.md)
-    * [Choosing Fields and Embedded Resources](rest-api-guidelines/quality/execution/choosing-fields-and-embedded-resoruces.md)
-    * [Localization](rest-api-guidelines/quality/execution/localization.md)
-    * [Rate Limiting](rest-api-guidelines/quality/execution/rate-limiting.md)
-    * [Caching](rest-api-guidelines/quality/execution/caching.md)
-    * [Testing Enviroments](rest-api-guidelines/quality/execution/testing-enviroments.md)
-  * [Evolution](rest-api-guidelines/quality/evolution/README.md)
-    * [Naming Conventions](rest-api-guidelines/quality/evolution/naming-conventions.md)
-    * [Reserved Identifiers](rest-api-guidelines/quality/evolution/reserved-identifiers.md)
-    * [URI Structure](rest-api-guidelines/quality/evolution/uri-structure.md)
-    * [Changes and Versioning](rest-api-guidelines/quality/evolution/versioning.md)
-    * [Phasing out Old Versions](rest-api-guidelines/quality/evolution/phasing-out-old-versions.md)
+* [Protocol](rest-api-guidelines/protocol/README.md)
+  * [HTTP](rest-api-guidelines/protocol/http.md)
+  * [TLS](rest-api-guidelines/protocol/tls.md)
+  * [Separate Concerns](rest-api-guidelines/protocol/separate-concerns.md)
+  * [Request Methods](rest-api-guidelines/protocol/use-appropriate-methods.md)
+  * [Status Codes](rest-api-guidelines/protocol/use-appropriate-status-codes.md)
+* [Message](rest-api-guidelines/message/README.md)
+  * [Message Formats](rest-api-guidelines/message/message-formats.md)
+  * [Content Negotiation](rest-api-guidelines/message/content-negotiation.md)
+  * [HAL](rest-api-guidelines/message/hal.md)
+  * [Problem Detail](rest-api-guidelines/message/error-reporting.md)
+  * [Foreign Key Relations](rest-api-guidelines/message/foreign-key-relations.md)
+* [Application](rest-api-guidelines/application/README.md)
+  * [Corporate Data Model](rest-api-guidelines/application/harmonize-data.md)
+  * [Common Data Types](rest-api-guidelines/application/common-data-types.md)
+* [Execution](rest-api-guidelines/execution/README.md)
+  * [Pagination](rest-api-guidelines/execution/pagination.md)
+  * [Asynchronous Tasks](rest-api-guidelines/execution/asynchronous-tasks.md)
+  * [Batch Operations](rest-api-guidelines/execution/batch-operations.md)
+  * [Search Requests](rest-api-guidelines/execution/search-requests.md)
+  * [Query Requests with Large Inputs](rest-api-guidelines/execution/query-requests-with-large-inputs.md)
+  * [Choosing Fields and Embedded Resources](rest-api-guidelines/execution/choosing-fields-and-embedded-resoruces.md)
+  * [Localization](rest-api-guidelines/execution/localization.md)
+  * [Rate Limiting](rest-api-guidelines/execution/rate-limiting.md)
+  * [Caching](rest-api-guidelines/execution/caching.md)
+  * [Testing Enviroments](rest-api-guidelines/execution/testing-enviroments.md)
+* [Evolution](rest-api-guidelines/evolution/README.md)
+  * [Naming Conventions](rest-api-guidelines/evolution/naming-conventions.md)
+  * [Reserved Identifiers](rest-api-guidelines/evolution/reserved-identifiers.md)
+  * [URI Structure](rest-api-guidelines/evolution/uri-structure.md)
+  * [Changes and Versioning](rest-api-guidelines/evolution/versioning.md)
+  * [Phasing out Old Versions](rest-api-guidelines/evolution/phasing-out-old-versions.md)
 * [Guides](rest-api-guidelines/guides/README.md)
   * [API Testing CI Environment](rest-api-guidelines/guides/api-testing-ci-environment.md)
   * [Complete API Development](rest-api-guidelines/guides/complete-api-development.md)

general-guidelines/json.md

@@ -2,7 +2,7 @@
 
 Any JSON-based message **MUST** conform to the following rules:
 
-1. All JSON field names **MUST** follow the [Naming Conventions ](../rest-api-guidelines/quality/evolution/naming-conventions.md)\(`camelCase`, American English, etc.\)
+1. All JSON field names **MUST** follow the [Naming Conventions ](../rest-api-guidelines/evolution/naming-conventions.md)\(`camelCase`, American English, etc.\)
 2. Field names **MUST** be ASCII alpha num characters, underscore \(`_`\) or dollar sign \(`$`\)
 3. Boolean fields **MUST NOT** be of `null` value
 4. Fields with `null` value **SHOULD** be omitted

rest-api-guidelines/application/README.md

@@ -2,5 +2,5 @@
 
 Every API **SHOULD** use company terms for resource names, relation names and representation message field names.
 
-Also, every API **MUST** follow the [naming conventions](../../quality/evolution/naming-conventions.md).
+Also, every API **MUST** follow the [naming conventions](../evolution/naming-conventions.md).
 

rest-api-guidelines/evolution/reserved-identifiers.md

@@ -4,8 +4,8 @@ The list of all reserved identifiers or identifiers with special meaning.
 
 ## Representation Format Fields
 
-* `_links` - [HAL](../../functionality/message/hal.md)
-* `_embedded` - [HAL](../../functionality/message/hal.md)
+* `_links` - [HAL](../message/hal.md)
+* `_embedded` - [HAL](../message/hal.md)
 
 ## Query Parameters
 

rest-api-guidelines/evolution/versioning.md

@@ -13,7 +13,7 @@ Any change to:
 4. **Relation** with other resources \(e.g Links\)  
 5. **Representation format** \(e.g. HTTP request and response bodies\)
 
-**MUST** follow the [**Rules for Extending**](../../../general-guidelines/rules-for-extending.md).
+**MUST** follow the [**Rules for Extending**](../../general-guidelines/rules-for-extending.md).
 
 ## Identifier Stability \(No URI Versioning\)
 
@@ -29,7 +29,7 @@ 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 into a **new resource variant**. Existing resource variant **MUST** be preserved.
 
 A change to _representation format_ **SHOULD NOT** result into a new resource variant.
 
@@ -41,7 +41,7 @@ Currently, optional URI Query Parameter `first` on an existing resource `/greeti
 
 > A representation format is the serialization format \(media type\) used in request and response bodies, and typically it represents a resource or its part, possibly with additional hypermedia controls.
 
-If a change can't follow the Rules for Extending the representation format media type **MUST** be changed. If the media type has been changed the previous media type, **MUST** be available via [Content Negotiation](../../functionality/message/content-negotiation.md).
+If a change can't follow the Rules for Extending the representation format media type **MUST** be changed. If the media type has been changed the previous media type, **MUST** be available via [Content Negotiation](../message/content-negotiation.md).
 
 If the media type conveys the version parameter, the version parameter **SHOULD** follow [Semantic versioning](http://semver.org/).
 

rest-api-guidelines/execution/batch-operations.md

@@ -70,7 +70,7 @@ However, in such an operation has to be provided such a non-atomic bulk operatio
 
 1. Non-atomic bulk operation **MUST** return a success status code \(e.g. **200 OK**\) only if every and all sub-operation succeeded.
 2. If any single one sub-operation fails the whole non-atomic bulk operation **MUST** return the respective **4xx** or **5xx** status code.
-3. In the case of a failure the response **MUST** contain the [problem detail](../../functionality/message/message-formats.md#error-response-format) information about every sub-operation that has failed.
+3. In the case of a failure the response **MUST** contain the [problem detail](../message/message-formats.md#error-response-format) information about every sub-operation that has failed.
 4. **The client MUST be aware that the operation is non-atomic and the even the operation might have failed some sub-operations were processed successfully.**
 
 ### Example

rest-api-guidelines/functionality/README.md

@@ -1,4 +0,0 @@
-# Functionality
-
-
-

rest-api-guidelines/message/hal.md

@@ -12,7 +12,7 @@ This document is an informal introduction to the HAL media type. For more detail
 
 HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL).
 
-YAML code snippets are provided for [OpenAPI Specification 2.0/Swagger](./HAL-snippet.yaml) and [OpenAPI Specification 3.x](./HAL-snippet-full-OpenApi3.yaml).
+YAML code snippets are provided for [OpenAPI Specification 2.0/Swagger](https://github.com/adidas/api-guidelines/tree/4a033eb0cf8ec582102c09c1eb5ba1fa8a5597d9/rest-api-guidelines/functionality/message/HAL-snippet.yaml) and [OpenAPI Specification 3.x](https://github.com/adidas/api-guidelines/tree/4a033eb0cf8ec582102c09c1eb5ba1fa8a5597d9/rest-api-guidelines/functionality/message/HAL-snippet-full-OpenApi3.yaml).
 
 ## Simple Document Example
 
@@ -123,4 +123,5 @@ For working with HAL and Node.js using [HALson npm package](https://www.npmjs.co
 
 ### Spring Framework
 
-Spring framework supports HAL out of the box. More info can be found in [Spring Documentation](https://spring.io/guides/gs/rest-hateoas/) and [examples](https://github.com/spring-guides/gs-rest-hateoas).
+Spring framework supports HAL out of the box. More info can be found in [Spring Documentation](https://spring.io/guides/gs/rest-hateoas/) and [examples](https://github.com/spring-guides/gs-rest-hateoas).
+

rest-api-guidelines/protocol/http.md

@@ -10,7 +10,7 @@ Once you are familiar with the **HTTP message structure** learn about the **HTTP
 
 Each HTTP request method, status code, and header have its semantics defined, and every API **MUST** strictly adhere to it.
 
-Follow the [Robustness Principle](../../../general-guidelines/robustness.md). Use only the HTTP request methods, response codes and HTTP headers you understand, be liberal in accepting others.
+Follow the [Robustness Principle](../../general-guidelines/robustness.md). Use only the HTTP request methods, response codes and HTTP headers you understand, be liberal in accepting others.
 
 ## Know HTTP
 

rest-api-guidelines/quality/README.md

@@ -1,4 +0,0 @@
-# Quality
-
-
-

rest-api-guidelines/rest.md

@@ -11,26 +11,26 @@ The REST API Guidelines are further split into the following parts:
   REST API Guidelines Core Principles defines the rules that **MUST** be followed at throughout the full API lifecycle.
 
 * **Functionality Guidelines**
-  * \*\*\*\*[**Protocol level**](functionality/protocol/)\*\*\*\*
+  * \*\*\*\*[**Protocol level**](protocol/)\*\*\*\*
 
     Protocol guidelines define the protocols used within the organization.
 
-  * \*\*\*\*[**Message level**](functionality/message/)\*\*\*\*
+  * \*\*\*\*[**Message level**](message/)\*\*\*\*
 
     The Message guidelines define the structure and semantics of messages used to exchange information.
 
-  * \*\*\*\*[**Application level**](functionality/application/)
+  * \*\*\*\*[**Application level**](application/)
 
     The Application guidelines define the definition and use of application-specific semantics.
 * **Quality Guidelines**
 
   Evolution and Execution guidelines define the rules for achieving the desired architectural qualities of systems.
 
-  * \*\*\*\*[**Evolution**](quality/evolution/)\*\*\*\*
+  * \*\*\*\*[**Evolution**](evolution/)\*\*\*\*
 
     Evolution qualities governance, such as testability, maintainability, extensibility, and scalability.
 
-  * \*\*\*\*[**Execution**](quality/execution/)\*\*\*\*
+  * \*\*\*\*[**Execution**](execution/)\*\*\*\*
 
     Execution qualities governance, such as security and usability.