From b10b5021481d499677ddade9d0dbc7b877f93677 Mon Sep 17 00:00:00 2001 From: apidesigner Date: Tue, 26 Feb 2019 10:35:35 +0000 Subject: [PATCH] GitBook: [master] 69 pages modified --- SUMMARY.md | 66 +++++++++---------- general-guidelines/json.md | 2 +- .../{functionality => }/application/README.md | 2 +- .../application/common-data-types.md | 0 .../application/harmonize-data.md | 0 .../{quality => }/evolution/README.md | 0 .../evolution/naming-conventions.md | 0 .../evolution/phasing-out-old-versions.md | 0 .../evolution/reserved-identifiers.md | 4 +- .../{quality => }/evolution/uri-structure.md | 0 .../{quality => }/evolution/versioning.md | 6 +- .../{quality => }/execution/README.md | 0 .../execution/asynchronous-tasks.md | 0 .../execution/batch-operations.md | 2 +- .../{quality => }/execution/caching.md | 0 .../choosing-fields-and-embedded-resoruces.md | 0 .../{quality => }/execution/localization.md | 0 .../{quality => }/execution/pagination.md | 0 .../query-requests-with-large-inputs.md | 0 .../{quality => }/execution/rate-limiting.md | 0 .../execution/search-requests.md | 0 .../execution/testing-enviroments.md | 0 rest-api-guidelines/functionality/README.md | 4 -- .../{functionality => }/message/README.md | 0 .../message/content-negotiation.md | 0 .../message/error-reporting.md | 0 .../message/foreign-key-relations.md | 0 .../{functionality => }/message/hal.md | 5 +- .../message/message-formats.md | 0 .../{functionality => }/protocol/README.md | 0 .../{functionality => }/protocol/http.md | 2 +- .../protocol/separate-concerns.md | 0 .../{functionality => }/protocol/tls.md | 0 .../protocol/use-appropriate-methods.md | 0 .../protocol/use-appropriate-status-codes.md | 0 rest-api-guidelines/quality/README.md | 4 -- rest-api-guidelines/rest.md | 10 +-- 37 files changed, 49 insertions(+), 58 deletions(-) rename rest-api-guidelines/{functionality => }/application/README.md (55%) rename rest-api-guidelines/{functionality => }/application/common-data-types.md (100%) rename rest-api-guidelines/{functionality => }/application/harmonize-data.md (100%) rename rest-api-guidelines/{quality => }/evolution/README.md (100%) rename rest-api-guidelines/{quality => }/evolution/naming-conventions.md (100%) rename rest-api-guidelines/{quality => }/evolution/phasing-out-old-versions.md (100%) rename rest-api-guidelines/{quality => }/evolution/reserved-identifiers.md (80%) rename rest-api-guidelines/{quality => }/evolution/uri-structure.md (100%) rename rest-api-guidelines/{quality => }/evolution/versioning.md (92%) rename rest-api-guidelines/{quality => }/execution/README.md (100%) rename rest-api-guidelines/{quality => }/execution/asynchronous-tasks.md (100%) rename rest-api-guidelines/{quality => }/execution/batch-operations.md (96%) rename rest-api-guidelines/{quality => }/execution/caching.md (100%) rename rest-api-guidelines/{quality => }/execution/choosing-fields-and-embedded-resoruces.md (100%) rename rest-api-guidelines/{quality => }/execution/localization.md (100%) rename rest-api-guidelines/{quality => }/execution/pagination.md (100%) rename rest-api-guidelines/{quality => }/execution/query-requests-with-large-inputs.md (100%) rename rest-api-guidelines/{quality => }/execution/rate-limiting.md (100%) rename rest-api-guidelines/{quality => }/execution/search-requests.md (100%) rename rest-api-guidelines/{quality => }/execution/testing-enviroments.md (100%) delete mode 100644 rest-api-guidelines/functionality/README.md rename rest-api-guidelines/{functionality => }/message/README.md (100%) rename rest-api-guidelines/{functionality => }/message/content-negotiation.md (100%) rename rest-api-guidelines/{functionality => }/message/error-reporting.md (100%) rename rest-api-guidelines/{functionality => }/message/foreign-key-relations.md (100%) rename rest-api-guidelines/{functionality => }/message/hal.md (92%) rename rest-api-guidelines/{functionality => }/message/message-formats.md (100%) rename rest-api-guidelines/{functionality => }/protocol/README.md (100%) rename rest-api-guidelines/{functionality => }/protocol/http.md (90%) rename rest-api-guidelines/{functionality => }/protocol/separate-concerns.md (100%) rename rest-api-guidelines/{functionality => }/protocol/tls.md (100%) rename rest-api-guidelines/{functionality => }/protocol/use-appropriate-methods.md (100%) rename rest-api-guidelines/{functionality => }/protocol/use-appropriate-status-codes.md (100%) delete mode 100644 rest-api-guidelines/quality/README.md diff --git a/SUMMARY.md b/SUMMARY.md index 8da6e68..7be3c21 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -22,40 +22,38 @@ * [API Design Platform](rest-api-guidelines/core-principles/apiary.md) * [Design Maturity](rest-api-guidelines/core-principles/design-maturity.md) * [Testing](rest-api-guidelines/core-principles/testing.md) -* [Functionality](rest-api-guidelines/functionality/README.md) - * [Protocol](rest-api-guidelines/functionality/protocol/README.md) - * [HTTP](rest-api-guidelines/functionality/protocol/http.md) - * [TLS](rest-api-guidelines/functionality/protocol/tls.md) - * [Separate Concerns](rest-api-guidelines/functionality/protocol/separate-concerns.md) - * [Request Methods](rest-api-guidelines/functionality/protocol/use-appropriate-methods.md) - * [Status Codes](rest-api-guidelines/functionality/protocol/use-appropriate-status-codes.md) - * [Message](rest-api-guidelines/functionality/message/README.md) - * [Message Formats](rest-api-guidelines/functionality/message/message-formats.md) - * [Content Negotiation](rest-api-guidelines/functionality/message/content-negotiation.md) - * [HAL](rest-api-guidelines/functionality/message/hal.md) - * [Problem Detail](rest-api-guidelines/functionality/message/error-reporting.md) - * [Foreign Key Relations](rest-api-guidelines/functionality/message/foreign-key-relations.md) - * [Application](rest-api-guidelines/functionality/application/README.md) - * [Corporate Data Model](rest-api-guidelines/functionality/application/harmonize-data.md) - * [Common Data Types](rest-api-guidelines/functionality/application/common-data-types.md) -* [Quality](rest-api-guidelines/quality/README.md) - * [Execution](rest-api-guidelines/quality/execution/README.md) - * [Pagination](rest-api-guidelines/quality/execution/pagination.md) - * [Asynchronous Tasks](rest-api-guidelines/quality/execution/asynchronous-tasks.md) - * [Batch Operations](rest-api-guidelines/quality/execution/batch-operations.md) - * [Search Requests](rest-api-guidelines/quality/execution/search-requests.md) - * [Query Requests with Large Inputs](rest-api-guidelines/quality/execution/query-requests-with-large-inputs.md) - * [Choosing Fields and Embedded Resources](rest-api-guidelines/quality/execution/choosing-fields-and-embedded-resoruces.md) - * [Localization](rest-api-guidelines/quality/execution/localization.md) - * [Rate Limiting](rest-api-guidelines/quality/execution/rate-limiting.md) - * [Caching](rest-api-guidelines/quality/execution/caching.md) - * [Testing Enviroments](rest-api-guidelines/quality/execution/testing-enviroments.md) - * [Evolution](rest-api-guidelines/quality/evolution/README.md) - * [Naming Conventions](rest-api-guidelines/quality/evolution/naming-conventions.md) - * [Reserved Identifiers](rest-api-guidelines/quality/evolution/reserved-identifiers.md) - * [URI Structure](rest-api-guidelines/quality/evolution/uri-structure.md) - * [Changes and Versioning](rest-api-guidelines/quality/evolution/versioning.md) - * [Phasing out Old Versions](rest-api-guidelines/quality/evolution/phasing-out-old-versions.md) +* [Protocol](rest-api-guidelines/protocol/README.md) + * [HTTP](rest-api-guidelines/protocol/http.md) + * [TLS](rest-api-guidelines/protocol/tls.md) + * [Separate Concerns](rest-api-guidelines/protocol/separate-concerns.md) + * [Request Methods](rest-api-guidelines/protocol/use-appropriate-methods.md) + * [Status Codes](rest-api-guidelines/protocol/use-appropriate-status-codes.md) +* [Message](rest-api-guidelines/message/README.md) + * [Message Formats](rest-api-guidelines/message/message-formats.md) + * [Content Negotiation](rest-api-guidelines/message/content-negotiation.md) + * [HAL](rest-api-guidelines/message/hal.md) + * [Problem Detail](rest-api-guidelines/message/error-reporting.md) + * [Foreign Key Relations](rest-api-guidelines/message/foreign-key-relations.md) +* [Application](rest-api-guidelines/application/README.md) + * [Corporate Data Model](rest-api-guidelines/application/harmonize-data.md) + * [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) + * [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) + * [Choosing Fields and Embedded Resources](rest-api-guidelines/execution/choosing-fields-and-embedded-resoruces.md) + * [Localization](rest-api-guidelines/execution/localization.md) + * [Rate Limiting](rest-api-guidelines/execution/rate-limiting.md) + * [Caching](rest-api-guidelines/execution/caching.md) + * [Testing Enviroments](rest-api-guidelines/execution/testing-enviroments.md) +* [Evolution](rest-api-guidelines/evolution/README.md) + * [Naming Conventions](rest-api-guidelines/evolution/naming-conventions.md) + * [Reserved Identifiers](rest-api-guidelines/evolution/reserved-identifiers.md) + * [URI Structure](rest-api-guidelines/evolution/uri-structure.md) + * [Changes and Versioning](rest-api-guidelines/evolution/versioning.md) + * [Phasing out Old Versions](rest-api-guidelines/evolution/phasing-out-old-versions.md) * [Guides](rest-api-guidelines/guides/README.md) * [API Testing CI Environment](rest-api-guidelines/guides/api-testing-ci-environment.md) * [Complete API Development](rest-api-guidelines/guides/complete-api-development.md) diff --git a/general-guidelines/json.md b/general-guidelines/json.md index d2baa25..2c07784 100644 --- a/general-guidelines/json.md +++ b/general-guidelines/json.md @@ -2,7 +2,7 @@ Any JSON-based message **MUST** conform to the following rules: -1. All JSON field names **MUST** follow the [Naming Conventions ](../rest-api-guidelines/quality/evolution/naming-conventions.md)\(`camelCase`, American English, etc.\) +1. All JSON field names **MUST** follow the [Naming Conventions ](../rest-api-guidelines/evolution/naming-conventions.md)\(`camelCase`, American English, etc.\) 2. Field names **MUST** be ASCII alpha num characters, underscore \(`_`\) or dollar sign \(`$`\) 3. Boolean fields **MUST NOT** be of `null` value 4. Fields with `null` value **SHOULD** be omitted diff --git a/rest-api-guidelines/functionality/application/README.md b/rest-api-guidelines/application/README.md similarity index 55% rename from rest-api-guidelines/functionality/application/README.md rename to rest-api-guidelines/application/README.md index 059d50f..245e74a 100644 --- a/rest-api-guidelines/functionality/application/README.md +++ b/rest-api-guidelines/application/README.md @@ -2,5 +2,5 @@ Every API **SHOULD** use company terms for resource names, relation names and representation message field names. -Also, every API **MUST** follow the [naming conventions](../../quality/evolution/naming-conventions.md). +Also, every API **MUST** follow the [naming conventions](../evolution/naming-conventions.md). diff --git a/rest-api-guidelines/functionality/application/common-data-types.md b/rest-api-guidelines/application/common-data-types.md similarity index 100% rename from rest-api-guidelines/functionality/application/common-data-types.md rename to rest-api-guidelines/application/common-data-types.md diff --git a/rest-api-guidelines/functionality/application/harmonize-data.md b/rest-api-guidelines/application/harmonize-data.md similarity index 100% rename from rest-api-guidelines/functionality/application/harmonize-data.md rename to rest-api-guidelines/application/harmonize-data.md diff --git a/rest-api-guidelines/quality/evolution/README.md b/rest-api-guidelines/evolution/README.md similarity index 100% rename from rest-api-guidelines/quality/evolution/README.md rename to rest-api-guidelines/evolution/README.md diff --git a/rest-api-guidelines/quality/evolution/naming-conventions.md b/rest-api-guidelines/evolution/naming-conventions.md similarity index 100% rename from rest-api-guidelines/quality/evolution/naming-conventions.md rename to rest-api-guidelines/evolution/naming-conventions.md diff --git a/rest-api-guidelines/quality/evolution/phasing-out-old-versions.md b/rest-api-guidelines/evolution/phasing-out-old-versions.md similarity index 100% rename from rest-api-guidelines/quality/evolution/phasing-out-old-versions.md rename to rest-api-guidelines/evolution/phasing-out-old-versions.md diff --git a/rest-api-guidelines/quality/evolution/reserved-identifiers.md b/rest-api-guidelines/evolution/reserved-identifiers.md similarity index 80% rename from rest-api-guidelines/quality/evolution/reserved-identifiers.md rename to rest-api-guidelines/evolution/reserved-identifiers.md index 113ad49..20a832d 100644 --- a/rest-api-guidelines/quality/evolution/reserved-identifiers.md +++ b/rest-api-guidelines/evolution/reserved-identifiers.md @@ -4,8 +4,8 @@ The list of all reserved identifiers or identifiers with special meaning. ## Representation Format Fields -* `_links` - [HAL](../../functionality/message/hal.md) -* `_embedded` - [HAL](../../functionality/message/hal.md) +* `_links` - [HAL](../message/hal.md) +* `_embedded` - [HAL](../message/hal.md) ## Query Parameters diff --git a/rest-api-guidelines/quality/evolution/uri-structure.md b/rest-api-guidelines/evolution/uri-structure.md similarity index 100% rename from rest-api-guidelines/quality/evolution/uri-structure.md rename to rest-api-guidelines/evolution/uri-structure.md diff --git a/rest-api-guidelines/quality/evolution/versioning.md b/rest-api-guidelines/evolution/versioning.md similarity index 92% rename from rest-api-guidelines/quality/evolution/versioning.md rename to rest-api-guidelines/evolution/versioning.md index 9ec3262..9a1073f 100644 --- a/rest-api-guidelines/quality/evolution/versioning.md +++ b/rest-api-guidelines/evolution/versioning.md @@ -13,7 +13,7 @@ Any change to: 4. **Relation** with other resources \(e.g Links\) 5. **Representation format** \(e.g. HTTP request and response bodies\) -**MUST** follow the [**Rules for Extending**](../../../general-guidelines/rules-for-extending.md). +**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](../../../general-guidelines/rules-for-extending.md) **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](../../functionality/message/content-negotiation.md). +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](../message/content-negotiation.md). If the media type conveys the version parameter, the version parameter **SHOULD** follow [Semantic versioning](http://semver.org/). diff --git a/rest-api-guidelines/quality/execution/README.md b/rest-api-guidelines/execution/README.md similarity index 100% rename from rest-api-guidelines/quality/execution/README.md rename to rest-api-guidelines/execution/README.md diff --git a/rest-api-guidelines/quality/execution/asynchronous-tasks.md b/rest-api-guidelines/execution/asynchronous-tasks.md similarity index 100% rename from rest-api-guidelines/quality/execution/asynchronous-tasks.md rename to rest-api-guidelines/execution/asynchronous-tasks.md diff --git a/rest-api-guidelines/quality/execution/batch-operations.md b/rest-api-guidelines/execution/batch-operations.md similarity index 96% rename from rest-api-guidelines/quality/execution/batch-operations.md rename to rest-api-guidelines/execution/batch-operations.md index 0ec37a5..c433c65 100644 --- a/rest-api-guidelines/quality/execution/batch-operations.md +++ b/rest-api-guidelines/execution/batch-operations.md @@ -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](../../functionality/message/message-formats.md#error-response-format) information about every sub-operation that has failed. +3. In the case of a failure the response **MUST** contain the [problem detail](../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 diff --git a/rest-api-guidelines/quality/execution/caching.md b/rest-api-guidelines/execution/caching.md similarity index 100% rename from rest-api-guidelines/quality/execution/caching.md rename to rest-api-guidelines/execution/caching.md diff --git a/rest-api-guidelines/quality/execution/choosing-fields-and-embedded-resoruces.md b/rest-api-guidelines/execution/choosing-fields-and-embedded-resoruces.md similarity index 100% rename from rest-api-guidelines/quality/execution/choosing-fields-and-embedded-resoruces.md rename to rest-api-guidelines/execution/choosing-fields-and-embedded-resoruces.md diff --git a/rest-api-guidelines/quality/execution/localization.md b/rest-api-guidelines/execution/localization.md similarity index 100% rename from rest-api-guidelines/quality/execution/localization.md rename to rest-api-guidelines/execution/localization.md diff --git a/rest-api-guidelines/quality/execution/pagination.md b/rest-api-guidelines/execution/pagination.md similarity index 100% rename from rest-api-guidelines/quality/execution/pagination.md rename to rest-api-guidelines/execution/pagination.md diff --git a/rest-api-guidelines/quality/execution/query-requests-with-large-inputs.md b/rest-api-guidelines/execution/query-requests-with-large-inputs.md similarity index 100% rename from rest-api-guidelines/quality/execution/query-requests-with-large-inputs.md rename to rest-api-guidelines/execution/query-requests-with-large-inputs.md diff --git a/rest-api-guidelines/quality/execution/rate-limiting.md b/rest-api-guidelines/execution/rate-limiting.md similarity index 100% rename from rest-api-guidelines/quality/execution/rate-limiting.md rename to rest-api-guidelines/execution/rate-limiting.md diff --git a/rest-api-guidelines/quality/execution/search-requests.md b/rest-api-guidelines/execution/search-requests.md similarity index 100% rename from rest-api-guidelines/quality/execution/search-requests.md rename to rest-api-guidelines/execution/search-requests.md diff --git a/rest-api-guidelines/quality/execution/testing-enviroments.md b/rest-api-guidelines/execution/testing-enviroments.md similarity index 100% rename from rest-api-guidelines/quality/execution/testing-enviroments.md rename to rest-api-guidelines/execution/testing-enviroments.md diff --git a/rest-api-guidelines/functionality/README.md b/rest-api-guidelines/functionality/README.md deleted file mode 100644 index e10f223..0000000 --- a/rest-api-guidelines/functionality/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Functionality - - - diff --git a/rest-api-guidelines/functionality/message/README.md b/rest-api-guidelines/message/README.md similarity index 100% rename from rest-api-guidelines/functionality/message/README.md rename to rest-api-guidelines/message/README.md diff --git a/rest-api-guidelines/functionality/message/content-negotiation.md b/rest-api-guidelines/message/content-negotiation.md similarity index 100% rename from rest-api-guidelines/functionality/message/content-negotiation.md rename to rest-api-guidelines/message/content-negotiation.md diff --git a/rest-api-guidelines/functionality/message/error-reporting.md b/rest-api-guidelines/message/error-reporting.md similarity index 100% rename from rest-api-guidelines/functionality/message/error-reporting.md rename to rest-api-guidelines/message/error-reporting.md diff --git a/rest-api-guidelines/functionality/message/foreign-key-relations.md b/rest-api-guidelines/message/foreign-key-relations.md similarity index 100% rename from rest-api-guidelines/functionality/message/foreign-key-relations.md rename to rest-api-guidelines/message/foreign-key-relations.md diff --git a/rest-api-guidelines/functionality/message/hal.md b/rest-api-guidelines/message/hal.md similarity index 92% rename from rest-api-guidelines/functionality/message/hal.md rename to rest-api-guidelines/message/hal.md index f4b4361..11a2569 100644 --- a/rest-api-guidelines/functionality/message/hal.md +++ b/rest-api-guidelines/message/hal.md @@ -12,7 +12,7 @@ This document is an informal introduction to the HAL media type. For more detail HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL). -YAML code snippets are provided for [OpenAPI Specification 2.0/Swagger](./HAL-snippet.yaml) and [OpenAPI Specification 3.x](./HAL-snippet-full-OpenApi3.yaml). +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). ## Simple Document Example @@ -123,4 +123,5 @@ For working with HAL and Node.js using [HALson npm package](https://www.npmjs.co ### 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). \ No newline at end of file +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). + diff --git a/rest-api-guidelines/functionality/message/message-formats.md b/rest-api-guidelines/message/message-formats.md similarity index 100% rename from rest-api-guidelines/functionality/message/message-formats.md rename to rest-api-guidelines/message/message-formats.md diff --git a/rest-api-guidelines/functionality/protocol/README.md b/rest-api-guidelines/protocol/README.md similarity index 100% rename from rest-api-guidelines/functionality/protocol/README.md rename to rest-api-guidelines/protocol/README.md diff --git a/rest-api-guidelines/functionality/protocol/http.md b/rest-api-guidelines/protocol/http.md similarity index 90% rename from rest-api-guidelines/functionality/protocol/http.md rename to rest-api-guidelines/protocol/http.md index 85b68d7..364565f 100644 --- a/rest-api-guidelines/functionality/protocol/http.md +++ b/rest-api-guidelines/protocol/http.md @@ -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](../../../general-guidelines/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 diff --git a/rest-api-guidelines/functionality/protocol/separate-concerns.md b/rest-api-guidelines/protocol/separate-concerns.md similarity index 100% rename from rest-api-guidelines/functionality/protocol/separate-concerns.md rename to rest-api-guidelines/protocol/separate-concerns.md diff --git a/rest-api-guidelines/functionality/protocol/tls.md b/rest-api-guidelines/protocol/tls.md similarity index 100% rename from rest-api-guidelines/functionality/protocol/tls.md rename to rest-api-guidelines/protocol/tls.md diff --git a/rest-api-guidelines/functionality/protocol/use-appropriate-methods.md b/rest-api-guidelines/protocol/use-appropriate-methods.md similarity index 100% rename from rest-api-guidelines/functionality/protocol/use-appropriate-methods.md rename to rest-api-guidelines/protocol/use-appropriate-methods.md diff --git a/rest-api-guidelines/functionality/protocol/use-appropriate-status-codes.md b/rest-api-guidelines/protocol/use-appropriate-status-codes.md similarity index 100% rename from rest-api-guidelines/functionality/protocol/use-appropriate-status-codes.md rename to rest-api-guidelines/protocol/use-appropriate-status-codes.md diff --git a/rest-api-guidelines/quality/README.md b/rest-api-guidelines/quality/README.md deleted file mode 100644 index dab3552..0000000 --- a/rest-api-guidelines/quality/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Quality - - - diff --git a/rest-api-guidelines/rest.md b/rest-api-guidelines/rest.md index a16c1c0..f709f91 100644 --- a/rest-api-guidelines/rest.md +++ b/rest-api-guidelines/rest.md @@ -11,26 +11,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**](functionality/protocol/)\*\*\*\* + * \*\*\*\*[**Protocol level**](protocol/)\*\*\*\* Protocol guidelines define the protocols used within the organization. - * \*\*\*\*[**Message level**](functionality/message/)\*\*\*\* + * \*\*\*\*[**Message level**](message/)\*\*\*\* The Message guidelines define the structure and semantics of messages used to exchange information. - * \*\*\*\*[**Application level**](functionality/application/) + * \*\*\*\*[**Application level**](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**](quality/evolution/)\*\*\*\* + * \*\*\*\*[**Evolution**](evolution/)\*\*\*\* Evolution qualities governance, such as testability, maintainability, extensibility, and scalability. - * \*\*\*\*[**Execution**](quality/execution/)\*\*\*\* + * \*\*\*\*[**Execution**](execution/)\*\*\*\* Execution qualities governance, such as security and usability.