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