From e95e6da5b8ea5f5e8341bd2f7a12c1b0ca7352f7 Mon Sep 17 00:00:00 2001 From: Myron Walker Date: Thu, 14 Sep 2023 15:11:58 -0500 Subject: [PATCH 1/3] Add an initial draft for a proposal for an 'archetype' field for path specifications. --- .../2023-09-14-Path-Archetype-Property-.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 proposals/2023-09-14-Path-Archetype-Property-.md diff --git a/proposals/2023-09-14-Path-Archetype-Property-.md b/proposals/2023-09-14-Path-Archetype-Property-.md new file mode 100644 index 0000000000..721b12ba3b --- /dev/null +++ b/proposals/2023-09-14-Path-Archetype-Property-.md @@ -0,0 +1,84 @@ +# Feature name +Path Archetype Property + +## Metadata + +|Tag |Value | +|---- | ---------------- | +|Proposal |[2023-09-14-Path-Archetype-Property](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{2023-09-14-Path-Archetype-Property.md})| +|Authors|[Myron W. Walker](https://github.com/myronww)| +|Review Manager | TBD | +|Status |Proposal| +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name}/implementations.md)| +|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{IssueId})| +|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | + +## Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | + +## Introduction + +Provide a mechanism to convey path "archetype" information or information about the architectural patterns that a path implements. + +## Motivation + +When working with larger product API sets that span multiple features and teams, it is important to ensure that the "Paths" associated with the different features produce consistent patterns of behavior across the entire product API. It is also equally important that API Paths communicate any patterns they are attempting to implement to the tools that will work with the API reflection document. + +When API paths sets are tested, the tests need to ensure that the path, properly implements all aspects of specific archetypical patterns. For example, an api path that implements a 'editable-collection' pattern for users on '/v1/users/' might need to adhere to the following set of design rules: + +* Provide a 'post' method for creating new collection items +* Provide a 'delete' method for removing items from the collection +* Provide a 'get' method for listing the items in the collection +* Provide a 'patch' method for updating an item +* Provide a 'put' method for replacing an item +* Return data in a standard collection form { items: [...], "total-count"=100, "page-count"=10, "page-num"=1, pages=10 } + +Having the information about the archetype that an API is supposed to implement is critical for testing to ensure that the APIs are meeting architectural standards across the entire API. + +Also, when API path information is consumed by a code generation tool that is attempting to create an interop client, the tool can utilize the archetype information declared for a path to help tune the generated code to better align with the intended behavioral patterns and functionality. + +By providing archetype desciptions for paths, the OpenAPI document can play a vital role in ensuring that APIs are testable across larger API sets and that code generators have the informaiton they need to properly implement API interop patterns for APIs. + +## Proposed solution + +The proposed solution is to add an 'archetype' field that is declared for a path. The archetype field provides a unique identifier that describes any special architectural design rules that a path should follow in its implementation and that provides detailed design information for code generation tool creators. + +## Detailed design + +To provide archetype information for paths, this design would add a field called 'archetype' to the 'path' specification. + +The schema for a path-item would be modified to include an optional 'archetype' property. + +"archetype": { + "type": "string", + "optional": true +}, + +The type of the new field is a string. This would allow for any unique identifier to be used, but would also allow for URL based identifiers Allowing for URL based identifiers means that the archetype field value can both serve as a unique identifier and at the same time refer an observer to a document that describes the design of the architypal pattern being declared. + +The use of URLs for the archetype identifier would also allow for standard archetypes to be published for consumption and sharing across API sets. + +As an example of how this might show up in an API set is in the design of APIs used to manage a collection of users. + +"/v1/users": { + "summary": "Path for working with the collection of users." + "archetype": "http://someorg.com/api-docs/design/collection.md" +} + + +"/v1/users/{user-id}": { + "summary": "Path for working with a single user." + "archetype": "http://someorg.com/api-docs/design/collection-item.md" +} + + +## Backwards compatibility + +The addition of a new field should not impact older code unless if the code was implemented with overly strict document processing mannerisms that will not handle the addition of a new field. + +## Alternatives considered + +The addition of an 'archetype' field for the path is the most flexible way to convey architectural pattern information to the API consumers in a flexible way that does not require explicit design on the part of the standards governing body. + From e0e4a327315fff3acecd2b231be2f4eb5752b5d5 Mon Sep 17 00:00:00 2001 From: Myron Walker Date: Sat, 16 Sep 2023 07:23:22 -0500 Subject: [PATCH 2/3] Update 2023-09-14-Path-Archetype-Property-.md Fix minor typo --- proposals/2023-09-14-Path-Archetype-Property-.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2023-09-14-Path-Archetype-Property-.md b/proposals/2023-09-14-Path-Archetype-Property-.md index 721b12ba3b..38137b5c49 100644 --- a/proposals/2023-09-14-Path-Archetype-Property-.md +++ b/proposals/2023-09-14-Path-Archetype-Property-.md @@ -26,7 +26,7 @@ Provide a mechanism to convey path "archetype" information or information about When working with larger product API sets that span multiple features and teams, it is important to ensure that the "Paths" associated with the different features produce consistent patterns of behavior across the entire product API. It is also equally important that API Paths communicate any patterns they are attempting to implement to the tools that will work with the API reflection document. -When API paths sets are tested, the tests need to ensure that the path, properly implements all aspects of specific archetypical patterns. For example, an api path that implements a 'editable-collection' pattern for users on '/v1/users/' might need to adhere to the following set of design rules: +When API path sets are tested, the tests need to ensure that the path, properly implements all aspects of specific archetypical patterns. For example, an api path that implements a 'editable-collection' pattern for users on '/v1/users/' might need to adhere to the following set of design rules: * Provide a 'post' method for creating new collection items * Provide a 'delete' method for removing items from the collection From f3e527a432ff9a2a17522c79c8e9cf3de04583ce Mon Sep 17 00:00:00 2001 From: Myron Walker Date: Tue, 19 Sep 2023 10:46:41 -0500 Subject: [PATCH 3/3] Minor update to tool motivation and issue id --- proposals/2023-09-14-Path-Archetype-Property-.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2023-09-14-Path-Archetype-Property-.md b/proposals/2023-09-14-Path-Archetype-Property-.md index 38137b5c49..dec48ec505 100644 --- a/proposals/2023-09-14-Path-Archetype-Property-.md +++ b/proposals/2023-09-14-Path-Archetype-Property-.md @@ -10,7 +10,7 @@ Path Archetype Property |Review Manager | TBD | |Status |Proposal| |Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name}/implementations.md)| -|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{IssueId})| +|Issues |[3372](https://github.com/OAI/OpenAPI-Specification/issues/3372)| |Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | ## Change Log @@ -37,7 +37,7 @@ When API path sets are tested, the tests need to ensure that the path, properly Having the information about the archetype that an API is supposed to implement is critical for testing to ensure that the APIs are meeting architectural standards across the entire API. -Also, when API path information is consumed by a code generation tool that is attempting to create an interop client, the tool can utilize the archetype information declared for a path to help tune the generated code to better align with the intended behavioral patterns and functionality. +When API path information is consumed by a code generation tool that is attempting to create an interop client, currently the tool must infer information about how to generate code for a path from different pieces of information from the URL, methods and method descriptions or possibly form method tags. This means that tools often cannot accurately distinguish implied patterns when bugs are present or missing elements of information. Tools can utilize the archetype identifier declared for a path to uniquely identify design and architectural patterns and then tune the generated code to better align with the intended behavioral patterns and functionality of an API By providing archetype desciptions for paths, the OpenAPI document can play a vital role in ensuring that APIs are testable across larger API sets and that code generators have the informaiton they need to properly implement API interop patterns for APIs.