mirror of
https://github.com/adidas/api-guidelines.git
synced 2025-10-25 15:19:19 +00:00
GitBook: [master] 102 pages and one asset modified
This commit is contained in:
apidesigner
gitbook-bot
@@ -1,2 +0,0 @@
|
||||
# Evolution
|
||||
Evolution qualities, such as testability, maintainability, extensibility, and scalability.
|
||||
@@ -1,117 +0,0 @@
|
||||
# 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
|
||||
```
|
||||
@@ -1,12 +0,0 @@
|
||||
# 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]()
|
||||
@@ -1,8 +0,0 @@
|
||||
# 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).
|
||||
@@ -1,102 +0,0 @@
|
||||
# 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)
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user