diff --git a/rest-api-guidelines/clients/loose-coupling.md b/rest-api-guidelines/clients/loose-coupling.md index 8206c7f..56a9851 100644 --- a/rest-api-guidelines/clients/loose-coupling.md +++ b/rest-api-guidelines/clients/loose-coupling.md @@ -1,6 +1,6 @@ # Loose Coupling -In addition to the [robustness principle](https://github.com/adidas-group/api-guidelines/tree/af88d15fd04ef18d6724fa65943901aab7328e7f/rest/clients/core-principles/robustness.md), API consumers \(clients\) **MUST** **operate independently** on API implementation's internals. Similarly the API consumers **MUST NOT** **assume** or **rely on** any knowledge of the API service internal implementation. +In addition to the [robustness principle](../../general-guidelines/robustness.md), API consumers \(clients\) **MUST** **operate independently** on API implementation's internals. Similarly the API consumers **MUST NOT** **assume** or **rely on** any knowledge of the API service internal implementation. Where available, the clients **SHOULD** utilize **hypermedia controls as the engine of the application state**, and rely on the **protocol, message and vocabulary semantics**. diff --git a/rest-api-guidelines/core-principles/apiary.md b/rest-api-guidelines/core-principles/apiary.md index f64c852..bb5c57d 100644 --- a/rest-api-guidelines/core-principles/apiary.md +++ b/rest-api-guidelines/core-principles/apiary.md @@ -1,7 +1,7 @@ # API Design Platform -1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](https://github.com/adidas-group/api-guidelines/tree/af88d15fd04ef18d6724fa65943901aab7328e7f/rest/core-principles/api-first.md). Apiary **MUST** be used during API Design. -2. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS GROUP team. +1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). Apiary **MUST** be used during API Design. +2. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS team. 3. Apiary **MUST** be the **single source of truth** to learn about existing APIs within the organization. > NOTE: Apiary supports API-first approach in multiple ways: diff --git a/rest-api-guidelines/functionality/application/README.md b/rest-api-guidelines/functionality/application/README.md index 2818d9a..059d50f 100644 --- a/rest-api-guidelines/functionality/application/README.md +++ b/rest-api-guidelines/functionality/application/README.md @@ -1,6 +1,6 @@ # Application -Every API SHOULD use company terms for resource names, relation names and representation message field names. +Every API **SHOULD** use company terms for resource names, relation names and representation message field names. -Also, every API MUST follow the [naming conventions](./). +Also, every API **MUST** follow the [naming conventions](../../quality/evolution/naming-conventions.md). diff --git a/rest-api-guidelines/functionality/protocol/http.md b/rest-api-guidelines/functionality/protocol/http.md index 63165a8..85b68d7 100644 --- a/rest-api-guidelines/functionality/protocol/http.md +++ b/rest-api-guidelines/functionality/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](https://github.com/adidas-group/api-guidelines/tree/af88d15fd04ef18d6724fa65943901aab7328e7f/rest/protocol/core-principles/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 diff --git a/rest-api-guidelines/guides/complete-api-development.md b/rest-api-guidelines/guides/complete-api-development.md index 4657be4..63ac3b4 100644 --- a/rest-api-guidelines/guides/complete-api-development.md +++ b/rest-api-guidelines/guides/complete-api-development.md @@ -15,7 +15,7 @@ > e.g.: User has many Orders via order relation, all of the required affordances should be mapped to relations. 5. Formalize the design in the [Open API Specification](http://swagger.io/specification/) \(OAS, formerly known as "Swagger"\) format - 6. Follow the [adidas API guidelines](https://adidas-group.gitbooks.io/api-guidelines/content/) + 6. Follow the [adidas API guidelines](https://adidas.gitbook.io/api-guidelines/introduction/readme) 7. Put the OAS file into [Apiary adidas group](https://apiary.io) 8. Make sure the OAS file passes all adidas API Apiary style guide checks 9. Verify the design using Apiary Documentation and Apiary Mock Service diff --git a/rest-api-guidelines/quality/evolution/naming-conventions.md b/rest-api-guidelines/quality/evolution/naming-conventions.md index 2456854..c6d12be 100644 --- a/rest-api-guidelines/quality/evolution/naming-conventions.md +++ b/rest-api-guidelines/quality/evolution/naming-conventions.md @@ -23,7 +23,7 @@ A well-formed URI: ### Query Parameters and Path Fragments -Every URI query parameter or fragment **MUST** follow the General Rules. Also, they **MUST NOT** clash with the [reserved query parameter names](https://tools.adidas-group.com/confluence/display/EA/API+Interaction#APIInteraction-Query_Parameters). +Every URI query parameter or fragment **MUST** follow the General Rules. Also, they **MUST NOT** clash with the [reserved query parameter names](reserved-identifiers.md#query-parameters). ### URI Template Variables diff --git a/rest-api-guidelines/quality/evolution/reserved-identifiers.md b/rest-api-guidelines/quality/evolution/reserved-identifiers.md index ade8812..113ad49 100644 --- a/rest-api-guidelines/quality/evolution/reserved-identifiers.md +++ b/rest-api-guidelines/quality/evolution/reserved-identifiers.md @@ -4,13 +4,13 @@ The list of all reserved identifiers or identifiers with special meaning. ## Representation Format Fields -* `_links` - [HAL](https://adidas-group.gitbooks.io/api-guidelines/content/message/hal.html) -* `_embedded` - [HAL](https://adidas-group.gitbooks.io/api-guidelines/content/message/hal.html) +* `_links` - [HAL](../../functionality/message/hal.md) +* `_embedded` - [HAL](../../functionality/message/hal.md) ## Query Parameters -* `fields`- [Choosing Fields & Embedded Resources](https://adidas-group.gitbooks.io/api-guidelines/content/execution/choosing-fields-and-embedded-resoruces.html) -* `embedded` - [Choosing Fields & Embedded Resources](https://adidas-group.gitbooks.io/api-guidelines/content/execution/choosing-fields-and-embedded-resoruces.html) -* `offset` - [Pagination](reserved-identifiers.md) -* `limit`- [Pagination](reserved-identifiers.md) +* `fields`- [Choosing Fields & Embedded Resources](../execution/choosing-fields-and-embedded-resoruces.md) +* `embedded` - [Choosing Fields & Embedded Resources](../execution/choosing-fields-and-embedded-resoruces.md) +* `offset` - [Pagination](../execution/pagination.md) +* `limit`- [Pagination](../execution/pagination.md) diff --git a/rest-api-guidelines/quality/evolution/uri-structure.md b/rest-api-guidelines/quality/evolution/uri-structure.md index f86375e..0c0886d 100644 --- a/rest-api-guidelines/quality/evolution/uri-structure.md +++ b/rest-api-guidelines/quality/evolution/uri-structure.md @@ -4,7 +4,7 @@ URI is meant to express a **identity of a resource**. URI is an identifier and i The API design process **MUST NOT** start with the design of URIs. Contrary, the URI **SHOULD** be amongst the last few things added to the API design. -At adidas, URIs are subject to [naming conventions](https://adidas-group.gitbooks.io/api-guidelines/content/evolution/naming-conventions.html). +At adidas, URIs are subject to [naming conventions](naming-conventions.md). To read more about the problematics refer to [RFC 7320: URI Design and Ownership](https://tools.ietf.org/html/rfc7320). diff --git a/rest-api-guidelines/quality/evolution/versioning.md b/rest-api-guidelines/quality/evolution/versioning.md index 55d90f8..cf127c9 100644 --- a/rest-api-guidelines/quality/evolution/versioning.md +++ b/rest-api-guidelines/quality/evolution/versioning.md @@ -13,7 +13,7 @@ Any change to: 1. **Relation** with other resources \(e.g Links\) 1. **Representation format** \(e.g. HTTP request and response bodies\) -**MUST** follow the [**Rules for Extending**](https://adidas-group.gitbooks.io/api-guidelines/content/core-principles/rules-for-extending.html). +**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](https://adidas-group.gitbooks.io/api-guidelines/content/core-principles/rules-for-extending.html) **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](https://adidas-group.gitbooks.io/api-guidelines/content/message/content-negotiation.html). +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 the media type conveys the version parameter, the version parameter **SHOULD** follow [Semantic versioning](http://semver.org/). diff --git a/rest-api-guidelines/quality/execution/batch-operations.md b/rest-api-guidelines/quality/execution/batch-operations.md index f141fa0..0ec37a5 100644 --- a/rest-api-guidelines/quality/execution/batch-operations.md +++ b/rest-api-guidelines/quality/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](https://adidas-group.gitbooks.io/api-guidelines/content/message/error-reporting.html) information about every sub-operation that has failed. +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. 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 diff --git a/rest-api-guidelines/quality/execution/search-requests.md b/rest-api-guidelines/quality/execution/search-requests.md index 1436efe..577991f 100644 --- a/rest-api-guidelines/quality/execution/search-requests.md +++ b/rest-api-guidelines/quality/execution/search-requests.md @@ -1,6 +1,6 @@ # Search Requests -A search \(filter\) operation on a collection resource **SHOULD** be defined as safe, idempotent and cacheable, therefore using the [GET HTTP request method](https://adidas-group.gitbooks.io/api-guidelines/content/protocol/use-appropriate-methods.html). +A search \(filter\) operation on a collection resource **SHOULD** be defined as safe, idempotent and cacheable, therefore using the GET HTTP request method. Every search parameter **SHOULD** be provided in the form of a query parameter. In the case of search parameters being mutually exclusive or require the presence of another parameter, the explanation **MUST** be part of operation's description. diff --git a/rest-api-guidelines/rest.md b/rest-api-guidelines/rest.md index 2bdd65d..bdf5ee9 100644 --- a/rest-api-guidelines/rest.md +++ b/rest-api-guidelines/rest.md @@ -13,26 +13,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**](https://adidas-group.gitbooks.io/api-guidelines/content/protocol/) + * \*\*\*\*[**Protocol level**](functionality/protocol/)\*\*\*\* Protocol guidelines define the protocols used within the organization. - * [**Message level**](https://adidas-group.gitbooks.io/api-guidelines/content/message/) + * \*\*\*\*[**Message level**](functionality/message/)\*\*\*\* The Message guidelines define the structure and semantics of messages used to exchange information. - * [**Application level**](https://adidas-group.gitbooks.io/api-guidelines/content/application/) + * \*\*\*\*[**Application level**](functionality/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**](https://adidas-group.gitbooks.io/api-guidelines/content/evolution/) + * \*\*\*\*[**Evolution**](quality/evolution/)\*\*\*\* Evolution qualities governance, such as testability, maintainability, extensibility, and scalability. - * [**Execution**](https://adidas-group.gitbooks.io/api-guidelines/content/execution/) + * \*\*\*\*[**Execution**](quality/execution/)\*\*\*\* Execution qualities governance, such as security and usability.