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

Changes related to Apiary and Mashery. Also related to LRTs cases and mentions to SwaggerHub.

Browse Source
This commit is contained in:
dediejes
2021-02-12 14:59:23 +01:00
parent d0b751e470
commit 82e9dd5bc9
21 changed files with 407 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -105,3 +105,5 @@ dist
# SSHFS
._*
.DS_Store

6
README.md
View File

@@ -4,7 +4,7 @@ description: Guidelines for the API design and development at adidas
# adidas API Guidelines
![adidas logo](https://adidas-group.gitbooks.io/api-guidelines/content/assets/adidas-logo.svg)
![adidas logo](adidaslogo.jpg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -23,7 +23,7 @@ The API Guidelines are split into two main parts:
* [General Guidelines](general-guidelines/general-guidelines.md)
* API type-specific Guidelines
* [REST APIs Guidelines](rest-api-guidelines/rest.md)
* [Kafka Guidelines](kafka-guidelines/kafka.md)
* [Asynchronous APIs Guidelines](asynchronous-api-guidelines/asyncapi.md)
The general guidelines section discusses the core principles relevant to any kind of API. The API type-specific section further defines the guidelines specific to a given architectural style or API technique \(such as REST, Kafka or GraphQL APIs\).
@@ -83,5 +83,5 @@ For further information open the [adidas terms and conditions](https://github.co
### License
[MIT](https://github.com/adidas-group/api-guidelines/tree/657bc6fd49f1499f10c30ab18420f4bdb7cd841b/LICENSE/README.md)
[MIT](https://github.com/adidas/api-guidelines/blob/master/LICENSE)

13
SUMMARY.md
View File

@@ -21,6 +21,7 @@
* [OpenAPI Specification](rest-api-guidelines/core-principles/openapi-specification.md)
* [API Design Platform](rest-api-guidelines/core-principles/design-platform.md)
* [Design Maturity](rest-api-guidelines/core-principles/design-maturity.md)
* [HATEOAS](rest-api-guidelines/core-principles/HATEOAS.md)
* [Testing](rest-api-guidelines/core-principles/testing.md)
* [Protocol](rest-api-guidelines/protocol/README.md)
* [HTTP](rest-api-guidelines/protocol/http.md)
@@ -39,7 +40,10 @@
* [Common Data Types](rest-api-guidelines/application/common-data-types.md)
* [Execution](rest-api-guidelines/execution/README.md)
* [Pagination](rest-api-guidelines/execution/pagination.md)
* [Asynchronous Tasks](rest-api-guidelines/execution/asynchronous-tasks.md)
* [Long Running Tasks](rest-api-guidelines/execution/long-running-tasks/README.md)
* [Polling](rest-api-guidelines/execution/long-running-tasks/polling.md)
* [Callback](rest-api-guidelines/execution/long-running-tasks/callback.md)
* [Files Upload](rest-api-guidelines/execution/long-running-tasks/files-upload.md)
* [Batch Operations](rest-api-guidelines/execution/batch-operations.md)
* [Search Requests](rest-api-guidelines/execution/search-requests.md)
* [Query Requests with Large Inputs](rest-api-guidelines/execution/query-requests-with-large-inputs.md)
@@ -61,7 +65,10 @@
* [Loose Coupling](rest-api-guidelines/clients/loose-coupling.md)
* [Further References](rest-api-guidelines/miscellaneous.md)
## Kafka Guidelines
## Asynchronous API Guidelines
* [Introduction](kafka-guidelines/kafka.md)
* [Introduction](asynchronous-api-guidelines/asyncapi.md)
* [Core Principles](asynchronous-api-guidelines/core-principles/README.md)
* [Platforms](asynchronous-api-guidelines/platforms/README.md)
* [Types](asynchronous-api-guidelines/types/README.md)

BIN
adidaslogo.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

6
asynchronous-api-guidelines/asyncapi.md Normal file
View File

@@ -0,0 +1,6 @@
# Introduction
## adidas Asynchronous APIs Guidelines

4
general-guidelines/json.md
View File

@@ -9,3 +9,7 @@ Any JSON-based message **MUST** conform to the following rules:
5. Empty arrays and objects **SHOULD NOT** be `null` \(use `[]` or `{}` instead\)
6. Array field names **SHOULD** be plural \(e.g. `"orders": []`\)
## Validation
All API designers **MUST** validate the definition of the payloads in requests/responses with the [JSON Schema](https://json-schema.org/) for the defined structure prior to the publication of the API Contract in SwaggerHub.
The publication of the JSON schema corresponding to the expected payloads in the bodies of requests and responses **SHOULD** be kept up to date according to the evolution of the API.

6
kafka-guidelines/kafka.md
View File

@@ -1,6 +0,0 @@
# Introduction
## adidas Kafka Guidelines

2
rest-api-guidelines/core-principles/design-platform.md
View File

@@ -1,6 +1,6 @@
# API Design Platform
1. [SwaggerHub](https://swagger.io/tools/swaggerhub/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). SwaggerHub **SHOULD** be used during API Design.
1. [SwaggerHub](https://design.api.3stripes.io/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). SwaggerHub **MUST** be used during API Design.
2. Every API description **MUST** be stored in [SwaggerHub](https://design.api.3stripes.io/) under the adidas team.
3. SwaggerHub **MUST** be the **single source of truth** to learn about existing APIs within the organization.

2
rest-api-guidelines/core-principles/openapi-specification.md
View File

@@ -1,6 +1,6 @@
# OpenAPI Specification
Every API **MUST** be described using an API description format. The API description format used MUST be the [OpenAPI Specification \(formerly known as Swagger Specification\) version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).
Every API **MUST** be described using an API description format. The API description format used MUST be the [OpenAPI Specification \(formerly known as Swagger Specification\) version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) OR the[OpenAPI Specification \(formerly known as Swagger Specification\) version 3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md).
Every API description **MUST** be published in adidas [API design platform](design-platform.md) and it **SHOULD** be stored in version control system \(Bitbucket, GitHub\) in the same repository as the API implementation.

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

@@ -2,7 +2,7 @@
## Processing Similar Resources
An operation that needs to process several related resources in bulk **SHOULD** use a collection resource with the appropriate HTTP Request Method. When processing existing resource the request message body **MUST** contain the URLs of the respective resources being processed.
An operation that needs to process several related resources in bulk **SHOULD** uses a collection resource with the appropriate HTTP Request Method. When processing existing resource the request message body **MUST** contain the URLs of the respective resources being processed.
### Example

34
rest-api-guidelines/execution/caching.md
View File

@@ -2,15 +2,43 @@
Every API implementation **SHOULD** return both the cache expiry information \([`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)\) and specific resource version information \([`ETag` HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)\).
## Cache-Control
The adidas API Gateway – [Kong](https://konghq.com/kong/) offers the cache feature to APIs to be applied to 1 or N endpoints or Consumer. So, cache fetures can be implemented at API Gateway level, upstream/backend service level or both.
## Cache-Control
Every API implementation's response **SHOULD** include information about cache-ability and cache expiration of the response. For HTTP 1.1 this is achieved using the `Cache-Control` header.
### Settings
#### adidas API Gateway
The configuration of cache in the adidas API Gateway is mainly based on:
- Cacheable HTTP methods
- When to cache. Response content types, headers to be considered for the cache key, relevant query parameters, etc.
- Expiration time, meaning the number of seconds to keep resources in the storage backend.
- Strategy. This means, which is the backing data store in which to hold cache entities. The only accepted values are `memory` and `redis`.
> A complete reference for configuration can be seen [here](https://docs.konghq.com/hub/kong-inc/proxy-cache/).
#### API Consumer
Clients **SHOULD** be capable of using `max-age` and `max-stale` headers to exclude the entity from being cached entirely or request stale copies of data if necessary.
### Common Cache-Control Scenarios
Two, most common scenarios for controlling the cache-ability of a response includes \(1\) Setting expiration and revalidation and \(2\) disabling the caching of a response. Refer to the [Cache-Control Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for additional controls.
> Remember the adidas API Gateway identifies the status of the request’s proxy cache behavior via the `X-Cache-Status` header. There are several possible values for this header:
- `Miss` The request could be satisfied in cache, but an entry for the resource was not found in cache, and the request was proxied upstream.
- `Hit` The request was satisfied and served from cache.
- `Refresh` The resource was found in cache, but could not satisfy the request, due to Cache-Control behaviors or reaching its hard-coded cache_ttl threshold.
- `Bypass` The request could not be satisfied from cache based on plugin configuration.
#### 1. Cache Expiration & Revalidation
Cache revalidation is not yet supported at API Gateway level.
The common scenario to set cache expiration and revalidation policy is to use the `max-age` and `must-revalidate` directives:
@@ -24,9 +52,11 @@ Content-Type: application/hal+json; charset=UTF-8
...
```
That means, `max-age` is the oldest that a response can be, as long as the Cache-Control from the origin server indicates that it is still fresh.
#### 2. Disabling Cache
To disable caching completely API implementation **SHOULD** use the `no-cache` and `no-store` directives:
At API Gateway and upstream/backend levels, to disable caching completely API implementation **SHOULD** use the `no-cache` directives:
```text
HTTP/1.1 200 OK

10
rest-api-guidelines/execution/long-running-tasks/README.md Normal file
View File

@@ -0,0 +1,10 @@
# Long Running Tasks
This section includes the recommended approaches to handling long runnint tasks (LRTs) in REST APIs.
You can identify a LRT quite easily. The main factor to consider are the metrics from latency of the endpoint. If it requiress tens of seconds even minutes we are facing a problem related to LRTs.
LRTs cannot be handled in a regular straight synchronous call. The amount of commited recources at the network, client and server levels are huge when connections are blocked for several minutes.
It is strongly recommended to follow a non-blocking solution as it is proposed in this section.

136
rest-api-guidelines/execution/long-running-tasks/callback.md Normal file
View File

@@ -0,0 +1,136 @@
# Callback
Callback or Webhooks are another way of handling long running tasks (LRTs). Callbacks are based on the subscription principle, whereas the API notifies the API Consumer in a different connection. This pattern is also applicable to the subscription to any kind of events to get notifications from your API.
The roles are:
- API Consumer / Subscriber
- API Producer / Publisher
If the chosen way is based on using callbacks, the response to such an asynchronous operation **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
> This pattern is described by [OAS v3.0.x](https://swagger.io/docs/specification/callbacks/).
## Subscription
The subscriber enrolls to specfic notifications. The subscriber resource **MUST** provide the information about the callback URL. Any data needed to require the execution of a task **MUST** be included in the request body.
The subscription is created by using the HTTP POST Request Method. It **SHOULD** be designed as follows:
1. Subscription is accepted
Return **201 Created** and representation of the current status. Content type: `application/hal+json`
The publisher resource **MUST** provide a UUID to identify the subscription.
2. Subscription is not accepted
Return **403 Forbidden** . Content type: `application/problem+json` with the problem detail information.
## Notification
The publisher resource **MUST** use callback URL provided by the subscriber. Any data with the output of the requested task **SHOULD** be sent to the subscriber in this request.
The callback request has to use the HTTP POST Request Method **SHOULD** as follows:
1. The subscriber accepts the callback. Content type: `application/hal+json`
Return **200 OK**.
2. The subscriber does not accept the callback
Return **403 Forbidden** . Content type: `application/problem+json` with the problem detail information.
## Cancel Subscription
The subscriber resource **MUST** include the UUID to identify the subscription.
It has to be used the HTTP PUT Request Method **SHOULD** as follows:
1. Subscription is accepted
Return **202 Accepted**. Content type: `application/hal+json`
2. Subscription is not accepted
Return **403 Forbidden** . Content type: `application/problem+json` with the problem detail information.
## Design Note
- The subscription pattern supports two main approaches:
- On one side, it can be **only-once**. The callback will be invoked only once by the publisher and it will be cancelled automatically after.
- On the other side, it can be **continuous**. In this case the subscription **MUST** be explicitly cancelled. Regarding the subscriber, its API is also the subject of the adidas API guidelines.
- The callback can be based on an Asynchronous/Streaming API topic. In this case the subscription is made as mentioned above but with the following differences in the workflow:
- The API Consumer does not send a callback URL in the initial request.
- The API Producer **SHOULD** provide the name of the topic and the UID of the task to correlate the input.
- It is up to the API Consumer to subscribe to the Asynchronous/Streaming API topic to receive the input from the provider. Please read the Asynchronous/Streaming API section.
### Example
1. **Settle the subscription**
```
POST /items/tasks/ HTTP/1.1
Content-Type: application/json
{
"callbackUrl": "https://myserver.com/send/callback/here"
}
...
HTTP/1.1 201 Created
Content-Type: application/hal+json
{
"_links": {
"self": { "href": "/items/tasks/4746" }
},
"message": "Your request to subscribe to the progress of the task has been accepted.",
"UUID": "4746"
}
```
2. **The Publisher sends the callback**
```
POST https://myserver.com/send/callback/here HTTP/1.1
{
"_links": {
"self": { "href": "/items/tasks/4746" }
},
"UUID": "4746",
{
<Data with the callback>
}
}
...
HTTP/1.1 200 Ok
Content-Type: application/hal+json
```
3. **Eventually the subscriber cancels the subscription**
```
PUT /feeds/tasks/1 HTTP/1.1
...
HTTP/1.1 202 Accepted
Content-Type: application/hal+json
{
"_links": {
"self": { "href": "/feeds/tasks/4746" }
},
"message": "Your subscription is cancelled."
}
```

82
rest-api-guidelines/execution/long-running-tasks/files-upload.md Normal file
View File

@@ -0,0 +1,82 @@
# Files Upload
The upload of files using a REST API endpoint is a common practice. It implies certain concerns taht have to be addressed in the design phase of the API.
The API Consumer performs a key role in this case. The MIME type in the Content-Type header of the request is an important factor for a successful operation. An operation that needs to upload binary files **SHOULD** uses a collection resource with the POST HTTP Request Method. When processing an existing resource the request message body **MUST** contain the right MIME type of the resources being processed.
## Main Issues
- Too long time periods in timeout settings, blocking open HTTP connections for too long. It makes the API less reliable and more error-prone as it is more vulnerable to network-related issues.
- Interrupted connections that can result into corrupted files and false response status to the API Consumer.
- No size limit in server can suppose an unacceptable load to the API operation in terms of resources, security and robustness as well as a huge increase in operational cost.
## Checklist in File Upload Operations
### Use the right MIME Type in the API Consumer Side
It is a common practice to use
[IANA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) distinguishes between two main generic types, **discrete** and **multipart**:
- Discrete types are types which represent a single file or medium, such as a single text, video, or music file.
- Multipart type represents a document that is comprised of multiple component parts, each of which may have its own individual MIME type. It can also encapsulate multiple files being sent together in one single transaction.
#### Using a Multipart Type
- multipart/form-data
- multipart/byteranges
Frameworks like Spring offfer support for multipart files sending like the [MultipartFile](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/multipart/MultipartFile.html) interface.
#### Using a Discrete Type
It is recommended to upload the file alone, with no other content in the request. This approach allows to include the MIME type corresponding to the specific type of file. For instance:
- Graphical file -> image/jpeg, image/gif, image/bmp, etc.
- Data file -> text/csv,
- Text file -> text/plain
- PDF -> application/pdf
etc.
It is also recommended to compress the file to be uploaded, then using these MIM types (examples):
- gzip -> application/gzip
- zip -> application/zip
- 7z -> application/x-7z-compressed
- tar -> application/x-tar
etc.
> You can find a complete reference about the MIME types [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types).
### Set Maximum Size Limit
The maximum size of the whole file **MUST** be set for the given endpoint/s in the APi upstream/backend service side.
The maximum size value depends on the use case and the expected payload in upload requests.
The settings **MUST** included in the upstream/backend service as a part of the configuration.
Otherwise, the API Gateway (Kong) **COULD** be configured enabling a maximum size of the payload for specific endpoint/s.
Frameworks like Spring includes configuration settings for multipart file uploading. The operation **SHOULD** be constrained as follows:
```
spring.servlet.multipart.enabled=true # enables multipart uploads
spring.servlet.multipart.file-size-threshold=2KB # the threshold after which files are written to disk.
spring.http.multipart.max-file-size=128KB # the total file size cannot exceed the amount o.
spring.http.multipart.max-request-size=128KB # the total request size for a multipart/form-data cannot exceed 128KB.
```
### Configure Properly all the Components
Load tests should give you metrics about the average latency of the operations. Use these metrics to calcuate the best value for the timeout settings in the upstream/backend service.
The API Gateway timeout settings have to be considered for the expected timeout values, aligned with the values in the upstream/backend service. Al other components in the infrastructure **MUST** be considered for the calculation of the final metrics.
```
|API Consumer/Client Timeout| ---> |External Load Balancer| ---> |API Gateway Timeout| ---> |Internal Load Balancer| ---> |Upstream/Backend Service Tiemout|
```
The approach based on too long timeout values is not acceptable. You **MUST** follow a fast-fail approach with a expected duration of the upload. If this time is exceeded a timeout error **SHOULD** be sent to the API Consumer. The maximum size limit **SHOULD** be consistent with the timeout value.
> Please also consider the client and API Gateway Timeout settings. In this case the lack of retrieval of a response during a too long upload operation can trigger a timeout error.

13
rest-api-guidelines/execution/asynchronous-tasks.md → rest-api-guidelines/execution/long-running-tasks/polling.md
View File

@@ -1,6 +1,6 @@
# Asynchronous Tasks
# Polling
If an API operation is asynchronous, but a client could track its progress, the response to such an asynchronous operation **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
If an API operation can be considered as a long running task and the API Consumer can track its progress, the response to the LRT **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
## Task Tracking Resource
@@ -22,13 +22,16 @@ Retrieval of such a resource using the HTTP GET Request Method **SHOULD** be des
## Design Note
The asynchronous operation task-tracking resource can be either **polled** by client or the client might initially provide a **callback** to be executed when the operation finishes.
The polling (task-tracking) operation requires a clear adaptation on the API Consumer side:
- Polling requests frequency depend on the type of operation and specific latency of thre resource.
- The identification of the resource has to be correlated along the series of polling requests. The API Consumer has to be able to save this ID and the API Producer has to be able to identify the progress of the operation with that ID.
- A security problem can be raised if a non-authorized client retrieves the response for a different resource ID. The authorization data and tasks in progress have to be strongly correlated and controlled to avoid consistency issues.
In the case of callback, the API and its client MUST agree on what HTTP method and request format is used for the callback invitation. If built within adidas, the "client" API is also the subject of the adidas API guidelines.
### Example
1. **Initiate the asynchronous task**
1. **Initiate the polling task**
```
POST /feeds/tasks/ HTTP/1.1

72
rest-api-guidelines/execution/rate-limiting.md
View File

@@ -1,69 +1,43 @@
# Rate Limiting
The API rate limiting is provided by the selected adidas API management platform – Mashery.
Rate limit means how many HTTP requests can be made in a given period of time.
Rate limit information is provided in the for of HTTP headers. There are two types of rate limits: **Quota** and **Throttle**. The quota is a limit enforced per a longer period \(typically a day\). The throttle is the limit of calls per second.
The API rate limiting is provided by the selected adidas API Gateway – [Kong](https://konghq.com/kong/). It can be applied to 1 or more endpoints or to the whole API.
## Quota Limit
Rate limit information is provided in the for of HTTP headers.
The limit on the number of calls per a period \(day\). The default quota limit is 5000 calls per day.
## Settings (adidas API Gateway)
### Example
The limit on the number of calls per a time period \(second, minute, hour, day, month, year\). The configuration settings have to be obtained from the Non-Functional Requirements of the API to be included as part of the settings of the API Gateway.
Example response to a request over the quota limit:
A complete reference for configuration can be seen [here](https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/execution/rate-limiting).
## Rate Limit
When this feature is enabled, the API Gateway will send some additional headers back to the client telling what are the limits allowed, how many requests are available and how long it will take until the quota will be restored. For instance (successful response):
```text
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
X-Error-Detail-Header: Account Over Rate Limit
X-Mashery-Error-Code: ERR_403_DEVELOPER_OVER_RATE
{
"title": "Rate Limit Exceeded",
"detail": "Account Over Rate Limit"
}
RateLimit-Limit: 6
RateLimit-Remaining: 4
RateLimit-Reset: 47
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9
```
## Throttle Limit
## Rate Limit Exceeded
The limit on the number of calls per second. The default throttle limit is two calls per second.
### Example
Example response to a request over the throttle limit:
If any of the limits configured in the API Gateway is being reached, it will return a HTTP/1.1 429 status code to the client:
```text
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-Error-Detail-Header: Account Over Queries Per Second Limit
X-Mashery-Error-Code: ERR_403_DEVELOPER_OVER_QPS
{
"title": "Quota Limit Exceeded",
"detail": "Account Over Queries Per Second Limit"
}
{ "message": "API rate limit exceeded" }
```
> NOTE: The `Retry-After` gives a hint how long before the same request should be repeated \(in seconds\).
## Detail Information
By default, the headers do not contain details about the current usage and quotas. The default can be changed in the API management.
### Example
A successful response with the details about throttle \(`X-Plan-QPS`\) and quota \(`X-Plan-Quota`\) rate limits:
```text
HTTP/1.1 200 OK
X-Plan-QPS-Allotted: 10
X-Plan-QPS-Current: 1
X-Plan-Quota-Allotted: 1000
X-Plan-Quota-Current: 2
X-Plan-Quota-Reset: Tuesday, June 6, 2017 12:00:00 AM GMT
```
> NOTE: The response header `Retry-After` gives a hint how long before the same request should be repeated \(in seconds\).

4
rest-api-guidelines/guides/api-testing-ci-environment.md
View File

@@ -10,7 +10,7 @@ The following must be available in the CI environment before testing:
```text
$ node -v
v12.16.0
v14.15.5
```
3. [**Dredd**](https://github.com/apiaryio/dredd) MUST be installed globally in the CI environment:
@@ -21,7 +21,7 @@ The following must be available in the CI environment before testing:
```text
$ dredd --version
dredd v13.0.1
dredd v14.0.0
```
## Testing an API

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

@@ -1,6 +1,6 @@
# Complete API Development
> NOTE: The content of this file is outdated, refering to previous technologies used at adidas. It is kept for reference until its refresh
1-Design --> 2-Develop --> 3-Deploy --> 4-API Gateway --> 5-Use --> 6-Analyze --> 7-Update
1. **Design the API**
1. Analyze business requirements
@@ -16,23 +16,25 @@
> 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"\) version 2.x or 3.0.x format.
> Use **[SwaggerHub](https://design.api.3stripes.io/)** for the whole design process to the publication of the API specification.
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
7. Publish the OAS file in SwaggerHub [under a specific project](https://design.api.3stripes.io/help/organizations/index) in the adidas organization.
8. Verify the OAS file you have written passes the Spectral test.
9. Make sure the OAS file passes all adidas SwaggerHub style guide checks. A red banned will be showed at the bottom of the editor if something is wrong with the OAS content.
10. Review the API Design
11. Put the OAS file in a version control system \(VCS\) repository
12. Set up a CD pipeline to push OAS file from VCS to Apiary, whenever the file is changed
12. Set up a CD pipeline to push OAS file from VCS to SwaggerHub, whenever the file is changed
2. **Develop the API**
1. Check out the VCS repository with the OAS file
2. Set up the [Dredd API testing tool](https://github.com/apiaryio/dredd) locally
3. Configure the Dredd for your project
```text
$ dredd init
```
4. Run the Dredd test locally
> Against locally running API implementation, Every test should fail.
@@ -41,74 +43,88 @@
> Keep running the Dredd locally to see the progress.
6. Set up a [CI/CD pipeline](https://adidas-group.gitbooks.io/api-guidelines/content/guides/api-testing-ci-environment.html) to execute the Dredd tests automatically
6. Set up a [CI/CD pipeline](https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/guides/api-testing-ci-environment) to execute the Dredd tests automatically.
> NOTE: Both TeamCity and Jenkins environments are available, contact adidas API Evangelist for details.
> NOTE: Both TeamCity and Jenkins environments are available, contact adidas API evangelist for details.
3. **Deploy the API**
1. Deploy the service
2. Update the OAS file to add the deployment HOST
2. Update the OAS file to add the deployment host (OAS v2.x) or the deployment servers (OAS v3.0.x). For instance:
> ```text
> host: adidas.api.mashery.com
> basePath: /demo-approval-api
> ```
OAS Version 2.x
```text
host: adidas.api.myapp.com
basePath: /demo-approval-api
```
OAS Version 3.0.x
```yaml
servers:
- url: https://adidas.api.myapp.com/
description: Production cluster
- url: http://stg.adidas.api.myapp.com/
description: Staging cluster
- url: http://dev.adidas.api.myapp.com/
description: Development cluster
```
3. Verify the deployment with Dredd
> Use Dredd pointed towards the deployment host, be careful NOT to run it against the production OR using real production credentials.
4. Monitor the API usage "From performance and technical standpoint."
4. **Expose the API using Mashery**
1. **API**
1. Create new API Definition in Mashery
2. Create a new API Endpoint the API Definition
4. **Expose the API using Kong**
> Ensure you have all the operational context information:
- Type of application
- Servers
- Detailed ownership information (Organiational unit, API Owner, Support contact, etc)
> Set the "Your Endpoint Address" to the internal deployment HOST.
> Ensure you have all the Non-Functional Requirements for your API like:
- Caching strategy detailed for each endpoint
- Rate Limits information
- Scope (internal to adidas or public)
- List of consumers and ACLs
- Authentication & Authorization
3. Create a new API Package in Mashery
4. Create a new API Plan within the API Package
5. Use Mashery API Designer to add the newly created API Definitions' API Endpoint to the API Plan
6. Revisit the API Plan's API key default settings
7. Revisit the API Plan's API default rate limits
8. Revisit the API Plan's access policy/authorization
9. **API Documentation**
1. Create new adidas API developer's portal page in the Mashery
Please read the [API On-Boarding Kong](https://tools.adidas-group.com/confluence/pages/viewpage.action?spaceKey=API2&title=Demand+-+API+Onboarding+in+Kong) to include your API in the adidas API Gateway if it is not done yet.
Once all the information is ready create an [on-boarding request in JIRA](https://tools.adidas-group.com/jira/Secure/CreateIssueDetails!Init.jspa?issuetype=3&pid=28605&issueTemplateId=3701&summary=null&priority=2&labels=Kong-Onboarding).
> Manage &gt; Content &gt; Documentation &gt; APIs
> Read the [API Team Service Catalog](https://tools.adidas-group.com/confluence/pages/viewpage.action?spaceKey=API2&title=Service+catalog) to get more information.
2. [Embed Apiary documentation](https://help.apiary.io/tools/embed/#apiary-embed-api-reference) on the newly created API Page
3. Revisit the API documentation access policy/authorization
5. **Use the API**
> This step can be done at the same time as "Develop the API" thank Apiary hosted Mock, Inspector, and Documentation.
> This step can be done at the same time as "Develop the API" using [SwaggerHub auto-mock service](https://design.api.3stripes.io/help/integrations/api-auto-mocking) and the continuous inspection of the OAS file.
1. Read API documentation at Apiary
2. Use API mock service provided by Apiary
3. Use API call inspector provided by Apiary
4. Obtain your API key
1. Read API documentation at SwaggerHub
2. Use an API implementation stub provided by SwaggerHub.
> The key is part of the API Plan created in Mashery and can be requested from your dashboard in the adidas API developer's portal.
> This is a good starting point for implementing the API, you can run and test it locally, implement the business logic for the API, and then deploy it to your server.
3. Obtain your API key and other information to apply the authentication/authorization mode in your API
5. When available use API implementation via Apiary proxy to debug the API calls
6. Use production deployment
> The key is part of the adidas API Gateway on-boarding process and can be requested from your dashboard in the adidas API developer's portal.
4. Use production deployment
6. **Analyze the API**
1. Examine the use of production API Using Mashery
1. Examine the use of production API Using Kong
2. Analyze the technical performance metrics
3. Collect the feedback from users
7. **Update API Design**
> Based on the analysis, new or changing business requirements
1. Create a new branch in the VCS repository with OAS file
2. Create a new project \(alternative\) in Apiary
2. Create a new project \(alternative\) in SwaggerHub
3. Make sure the CI/CD pipeline is:
1. Set to push the OAS file to Apiary but make sure to modify the Apiary project name
1. Set to push the OAS file to SwaggerHub but make sure to modify the SwaggerHub project name under the adidas organization
2. Set to run Dredd test in the CI/CD
4. Modify the design \(OAS file\) accordingly, follow the "Design API" step
5. Follow the [**rules for extending**](https://adidas-group.gitbooks.io/api-guidelines/content/core-principles/rules-for-extending.html) and [**adidas API guidelines versioning policies**](https://adidas-group.gitbooks.io/api-guidelines/content/evolution/versioning.html)
5. Follow the adidas API Guidelines for [**changes and versioning**](https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/evolution/versioning)
6. Use VCS pull request \(PR\) to propose the change to review
7. After the API Design change is verified, reviewed and approved, continue with the "Develop the API" phase
8. Eventually, when the updated design is ready to be deployed for production, merge the branch into the production branch
9. Follow this guide from "Expose the API using Mashery" step
9. Follow this guide from "Expose the API using Kong" step

21
rest-api-guidelines/message/hal.md
View File

@@ -1,16 +1,20 @@
# HAL
The [`application/hal+json`](http://stateless.co/hal_specification.html) \(HAL\) **MUST** be used as the representation format of a resource.
The Hypertext Application Language [`application/hal+json`](http://stateless.co/hal_specification.html) \(HAL\) **MUST** be used as the representation format of a resource.
## Introduction to HAL
> _HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API._
The HAL format is strictly coupled to [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS). The main target of HATEOAS is to decouple the API Consumer from the paths used ion the API. The API Client uses the links generated by our API instead of building them from the documentation. This is less eror-prone for the API Consumer and it can allow making changes in the API without affecting the API Consumer code.
This document is an informal introduction to the HAL media type. For more details see [HAL - Hypertext Application Language Specification](http://stateless.co/hal_specification.html).
## HAL Document Object Model
HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL).
HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL).
IANA created a list explaining the standard relationships for REST. Do not forget to have a look [here](http://www.iana.org/assignments/link-relations/link-relations.xhtml) to find the role of each type of relation.
YAML code snippets are provided for [OpenAPI Specification 2.0/Swagger](https://github.com/adidas/api-guidelines/tree/4a033eb0cf8ec582102c09c1eb5ba1fa8a5597d9/rest-api-guidelines/functionality/message/HAL-snippet.yaml) and [OpenAPI Specification 3.x](https://github.com/adidas/api-guidelines/tree/4a033eb0cf8ec582102c09c1eb5ba1fa8a5597d9/rest-api-guidelines/functionality/message/HAL-snippet-full-OpenApi3.yaml).
@@ -119,9 +123,18 @@ Some APIs using HAL:
Refer to the [extensive list of libraries that work with HAL](https://github.com/mikekelly/hal_specification/wiki/Libraries).
For working with HAL and Node.js using [HALson npm package](https://www.npmjs.com/package/halson) is suggested.
### Java
### Spring Framework
#### Spring Framework
Spring framework supports HAL out of the box. More info can be found in [Spring Documentation](https://spring.io/guides/gs/rest-hateoas/) and [examples](https://github.com/spring-guides/gs-rest-hateoas).
#### Quarkus Framework
Quarkus framework supports HAL out of the box. More info can be found in [Quarkus Documentation](https://quarkus.io/guides/rest-data-panache).
### NodeJS
For working with HAL and Node.js using [HALson npm package](https://www.npmjs.com/package/halson) is suggested.

7
rest-api-guidelines/miscellaneous.md
View File

@@ -8,3 +8,10 @@
## Tools documentation
* [SwaggerHub Documentation](https://app.swaggerhub.com/help/index)
## Learning Path (adidas-Udemy)
* [Basic](https://adidas-itlearning.udemy.com/course/onboarding-16-api-development-management/)
* [Deep Dive](https://adidas-itlearning.udemy.com/course/onboarding-21-api-development-management/)
* [OpenAPI](https://adidas-itlearning.udemy.com/course/openapi-beginner-to-guru/learn/)

2
rest-api-guidelines/protocol/use-appropriate-status-codes.md
View File

@@ -10,6 +10,8 @@ At a minimum everyone **MUST** be familiar with the semantics of ["Common" HTTP
## Use Codes 4xx or 5xx to Communicate Errors
Remember the 4xx range concern to errors in the API Consumer/Client side while 5xx range concerns to the upstream/backend service, the API implementation.
A request:
```text