Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

GitBook: [master] 12 pages modified

Browse Source
This commit is contained in:
apidesigner
2018-07-23 08:09:03 +00:00
committed by gitbook-bot
parent 3b81882249
commit 2f6bfab524
12 changed files with 25 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
rest-api-guidelines/clients/loose-coupling.md
View File

@@ -1,6 +1,6 @@
# Loose Coupling # 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**. Where available, the clients **SHOULD** utilize **hypermedia controls as the engine of the application state**, and rely on the **protocol, message and vocabulary semantics**.

4
rest-api-guidelines/core-principles/apiary.md
View File

@@ -1,7 +1,7 @@
# API Design Platform # 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. 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 GROUP team. 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. 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: > NOTE: Apiary supports API-first approach in multiple ways:

4
rest-api-guidelines/functionality/application/README.md
View File

@@ -1,6 +1,6 @@
# Application # 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).

2
rest-api-guidelines/functionality/protocol/http.md
View File

@@ -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. 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 ## Know HTTP

2
rest-api-guidelines/guides/complete-api-development.md
View File

@@ -15,7 +15,7 @@
> e.g.: User has many Orders via order relation, all of the required affordances should be mapped to relations. > 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 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) 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 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 9. Verify the design using Apiary Documentation and Apiary Mock Service

2
rest-api-guidelines/quality/evolution/naming-conventions.md
View File

@@ -23,7 +23,7 @@ A well-formed URI:
### Query Parameters and Path Fragments ### 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 ### URI Template Variables

12
rest-api-guidelines/quality/evolution/reserved-identifiers.md
View File

@@ -4,13 +4,13 @@ The list of all reserved identifiers or identifiers with special meaning.
## Representation Format Fields ## Representation Format Fields
* `_links` - [HAL](https://adidas-group.gitbooks.io/api-guidelines/content/message/hal.html) * `_links` - [HAL](../../functionality/message/hal.md)
* `_embedded` - [HAL](https://adidas-group.gitbooks.io/api-guidelines/content/message/hal.html) * `_embedded` - [HAL](../../functionality/message/hal.md)
## Query Parameters ## Query Parameters
* `fields`- [Choosing Fields & Embedded Resources](https://adidas-group.gitbooks.io/api-guidelines/content/execution/choosing-fields-and-embedded-resoruces.html) * `fields`- [Choosing Fields & Embedded Resources](../execution/choosing-fields-and-embedded-resoruces.md)
* `embedded` - [Choosing Fields & Embedded Resources](https://adidas-group.gitbooks.io/api-guidelines/content/execution/choosing-fields-and-embedded-resoruces.html) * `embedded` - [Choosing Fields & Embedded Resources](../execution/choosing-fields-and-embedded-resoruces.md)
* `offset` - [Pagination](reserved-identifiers.md) * `offset` - [Pagination](../execution/pagination.md)
* `limit`- [Pagination](reserved-identifiers.md) * `limit`- [Pagination](../execution/pagination.md)

2
rest-api-guidelines/quality/evolution/uri-structure.md
View File

@@ -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. 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). To read more about the problematics refer to [RFC 7320: URI Design and Ownership](https://tools.ietf.org/html/rfc7320).

6
rest-api-guidelines/quality/evolution/versioning.md
View File

@@ -13,7 +13,7 @@ Any change to:
1. **Relation** with other resources \(e.g Links\) 1. **Relation** with other resources \(e.g Links\)
1. **Representation format** \(e.g. HTTP request and response bodies\) 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\) ## 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 ## 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. 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. > 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/). If the media type conveys the version parameter, the version parameter **SHOULD** follow [Semantic versioning](http://semver.org/).

2
rest-api-guidelines/quality/execution/batch-operations.md
View File

@@ -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. 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. 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.** 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 ### Example

2
rest-api-guidelines/quality/execution/search-requests.md
View File

@@ -1,6 +1,6 @@
# Search Requests # 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. 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.

10
rest-api-guidelines/rest.md
View File

@@ -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. REST API Guidelines Core Principles defines the rules that **MUST** be followed at throughout the full API lifecycle.
* **Functionality Guidelines** * **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. 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. 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. The Application guidelines define the definition and use of application-specific semantics.
* **Quality Guidelines** * **Quality Guidelines**
Evolution and Execution guidelines define the rules for achieving the desired architectural qualities of systems. 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. 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. Execution qualities governance, such as security and usability.