Creates rest/core-principles/quality.md

Auto commit by GitBook Editor

rest/evolution/README.md

@@ -0,0 +1,2 @@
+# Evolution
+Evolution qualities, such as testability, maintainability, extensibility, and scalability.

rest/evolution/naming-conventions.md

@@ -0,0 +1,117 @@
+# Naming Conventions
+
+## General Naming Rules
+
+- Use American English
+- Don't use acronyms
+- Use `camelCase` unless stated otherwise
+- Reconcile terms with adidas CDM
+
+Every identifier **MUST** be in American English and written in `lowercase`. An identifier **SHOULD NOT** contain acronyms. CamelCase (`camelCase`) **MUST** be used to delimit combined words.
+
+## URI
+Every URI **MUST** follow the General Rules except for the `camelCase` rule. Instead, a hyphen (`-`) **SHOULD** be used to delimit combined words (kebab-case). Besides, a URI **MUST NOT** end with a trailing slash (`/`).
+
+#### Example
+A well-formed URI:
+
+```
+/system-orders/1234/author
+```
+
+### 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).
+
+### URI Template Variables
+In addition to General Naming Rules, URI Template Variable names **MUST** follow the [RFC6570](https://tools.ietf.org/html/rfc6570#section-2.3). That is, the variable names can consist only from `ALPHA / DIGIT / "_" / pct-encoded`.
+
+> NOTE: Per RFC6570 Hyphen (`-`) is NOT legal URI Template variable name character.
+
+#### Example
+A well-formed URI Template Variable:
+
+```
+/system-orders/{orderId}/author
+```
+
+## Representation Format Fields
+Every representation format field **MUST** conform to the General Naming Rules.
+
+#### Example
+A well-formed resource representation: 
+
+```json
+{
+  "_links": {
+    "self": {
+      "href": "/orders/1234"
+    },
+    "author": {
+      "href": "/users/john"
+    }
+  },
+  "orderNumber": 1234,
+  "itemCount": 42,
+  "status": "pending"
+}
+```
+
+## Relation Type Identifier
+Every custom [relation identifier](https://github.com/for-GET/know-your-http-well/blob/master/relations.md) **MUST** be in `lowercase` with words separated by the hyphen (`-`).
+
+#### Example
+A well-formed resource representation with custom relation `fulfillment-provider`: 
+
+```json
+{
+  "_links": {
+    "fulfillment-provider": {
+      "href": "/users/natalie"
+    }
+  }
+}
+```
+
+
+## HTTP Headers
+Every HTTP Header should use `Hyphenated-Pascal-Case`. A custom HTTP Header **SHOULD NOT** start with `X-` ([RFC6648](https://tools.ietf.org/html/rfc6648)).
+
+#### Example
+
+```
+Order-Metadata-Header: 42
+```
+
+
+## API Description
+Naming conventions within API Description document.
+
+### API Name
+Every API Description API name **MUST** start with API domain enclosed in square brackets (e.g. `[API Domain] My API`). Words **MUST** be separated by space.
+
+#### Example
+
+```yaml
+swagger: '2.0'
+info:
+  version: '1.0.0'
+  title: '[Demo] Orders API'
+```
+
+### Resource Name
+Every resource **MUST** have a name (defined by `x-summary` field). Resource name **MUST** be in `Title Case`. Words **MUST** be separated by a space.
+
+#### Example
+```yaml
+/orders:
+  x-summary: List of Orders
+```
+
+### Action Name
+Every action (operation) **MUST** have a name (defined by `summary` field). Action name **MUST** be in `Title Case`. Words **MUST** be separated by a space.
+
+#### Example
+```yaml
+get:
+  summary: Retrieve List of Orders
+```

rest/evolution/reserved-identifiers.md

@@ -0,0 +1,12 @@
+# Reserved Identifiers
+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)
+
+## 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]() 
+- `limit`- [Pagination]()

rest/evolution/uri-structure.md

@@ -0,0 +1,8 @@
+# URI Design 
+URI is meant to express a **identity of a resource**. URI is an identifier and it **MUST NOT** convey any other information.
+
+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).
+
+To read more about the problematics refer to [RFC 7320: URI Design and Ownership](https://tools.ietf.org/html/rfc7320).

rest/evolution/versioning.md

@@ -0,0 +1,102 @@
+# Changes and Versioning
+
+> _The fundamental principle is that you can’t break existing clients, because you don’t know what they implement, and you don’t control them. In doing so, you need to turn a backwards-incompatible change into a compatible one._
+>
+> _– _[_Mark Nottingham_](https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown)
+
+Any change to an API **MUST NOT** break existing clients.
+
+Any change to:  
+1. **Resource identifier** \(resource name / URI\) including any **query parameters** and their semantics  
+1. **Resource metadata** \(e.g. HTTP headers\)  
+1. **Action** the resource affords \(e.g. available HTTP Methods\)  
+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).
+
+## Identifier Stability \(No URI Versioning\)
+
+A change **MUST NOT** affect **existing** resource identifiers \(name / URI\). Furthermore, a resource identifier **MUST NOT** contain a semantic version to convey a version of resource or its representation format.
+
+> _The reason to make a real REST API is to get evolvability … a "v1" is a .... to your API customers, indicating RPC/HTTP \(not REST\)_
+>
+> _– _[_Roy T. Fielding_](https://twitter.com/fielding/status/376835835670167552)
+
+#### Example
+
+Adding a new action to existing resource with identifier `/greeting` doesn't change its identifier to `/v2/greeting` \(or `/greeting-with-new-action` etc.\).
+
+## 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 _representation format_ **SHOULD NOT** result into a new resource variant.
+
+#### Example
+
+Currently, optional URI Query Parameter `first` on an existing resource `/greeting?first=John&last=Appleseed` needs to be made required. Since this change violates the 3rd rule of extending and could break existing clients a new variant of the resource is created with different URI `/named-greeting?first=John&last=Appleseed`.
+
+### Representation Format Changes
+
+> 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 the media type conveys the version parameter, the version parameter **SHOULD** follow [Semantic versioning](http://semver.org/).
+
+#### Example
+
+Media type _before_ a breaking change:
+
+```
+application/vnd.example.resource+json; version=2
+```
+
+Media type _after_ a breaking change:
+
+```
+application/vnd.example.resource+json; version=3
+```
+
+> NOTE: In the case of technical limitations with semi-colon separated HTTP header values, the semantic version MAY be incorporated in the media type identifier, for example: `application/vnd.example.resource.v2+json` However, the use of semicolon-separated version information is preferred.
+
+## API Description Versioning
+
+API Description in the OpenAPI specification format **MUST** have the `version` field. The `version` field **MUST** follow [Semantic versioning](http://semver.org/):
+
+> Given a version number MAJOR.MINOR.PATCH, increment the:
+>
+> * MAJOR version when you make **incompatible** API changes,
+> * MINOR version when you add functionality in a **backwards-compatible** manner
+> * PATCH version when you make **backwards-compatible bug fixes**
+
+The API Description version **SHOULD** be updated accordingly to API design change.
+
+#### Example
+
+Following API Description
+
+```yaml
+swagger: '2.0'
+info:
+  version: '2.1.3'
+  title: '[Demo] Inventory API'
+  description: 'Inventory service API'
+```
+
+Has MAJOR version 2, MINOR version 1 and PATCH version 3.
+
+#### Demo
+
+API description \(OAS2\) files demonstrating a proposal of an backward-incompatible change turned into a backward compatible change are available at [Bitbucket \(diff\) ](https://bitbucket.org/apidesigner/demo-versioning-api/pull-requests/1/add-name-parameter/diff)and documented in Apiary:
+
+* [Production version](https://demoversioningproduction.docs.apiary.io/#) as being consumed by clients
+* [Development version](https://demoversioningdevelopment.docs.apiary.io/#) proposing a backward incompatible change
+
+#### Recommended Reading
+
+* [Evolving HTTP APIs](https://www.mnot.net/blog/2012/12/04/api-evolution)
+
+
+