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
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**.

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

@@ -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:

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

@@ -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).

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.
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

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.
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

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

@@ -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

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
* `_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)

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.
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).

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. **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/).

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.
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

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

@@ -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.

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.
* **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.