Add Arazzo workflow support (arazzo-v1, workflow capability, ord:orchestrates) - #158
Add Arazzo workflow support (arazzo-v1, workflow capability, ord:orchestrates)#158Fannon wants to merge 1 commit into
Conversation
…estrates) - New `arazzo-v1` resource definition type on API Resources (single-API workflows) - New `workflow` standardized Capability type + `arazzo-v1` capability definition type (multi-API workflows) - New `ord:orchestrates` relationType on `relatedApiResources` to declare which APIs a workflow invokes
|
| - const: arazzo-v1 | ||
| x-introduced-in-version: "1.16.4" | ||
| description: |- | ||
| [Arazzo Specification v1.0.0](https://spec.openapis.org/arazzo/v1.0.0.html) workflow document | ||
| describing multi-step API interactions. | ||
| The `mediaType` MUST be set to `application/json` or `application/yaml`. | ||
|
|
||
| Attaching an Arazzo definition to a single API Resource is ONLY appropriate when the | ||
| workflow is scoped to that specific API. For workflows that span multiple APIs, publish | ||
| a [Capability](#capability) with `type: "workflow"` and a definition of `type: "arazzo-v1"` instead, | ||
| and list every covered API via [`relatedApiResources`](#capability_relatedapiresources) with | ||
| `relationType: "ord:orchestrates"`. |
There was a problem hiding this comment.
Can always be a capability then, or?
There was a problem hiding this comment.
agree, the decision on API vs. Capability is unclear. How often to we have the use case of one API only arazzo definition? Do we need the complexity of adding it to API and as capability?
There was a problem hiding this comment.
Could be yes. But from what I've seen it doesn't seem uncommon to have a complementary Arazzo file for exactly one API, describing the flows within that one API. In this case it would be more convenient to have it directly attached to the API.
On the other hand, now we have two places where Arazzo could show up, which adds complexity as well.
Leaning toward making it a capability only
| description: |- | ||
| The source resource patches one or more definition files of the target resource. | ||
| Used on [ORD Overlay Resources](#overlay) to declare which API or Event resource they patch. | ||
| - const: "ord:orchestrates" |
There was a problem hiding this comment.
orchestrates
I think we should use "noun" as type names -> "orchestrator"
Can't it be also called ord:workflow here? Do we really need to introduce a new term?
There was a problem hiding this comment.
actually, we use verbs here x "patches" y
There was a problem hiding this comment.
Agree with Sebastian, I would prefer consistent verb use
| * If not provided, the relationship has no specific semantics ("related somehow"). | ||
| */ | ||
| relationType?: (string | "ord:patches") & string; | ||
| relationType?: (string | "ord:patches" | "ord:orchestrates") & string; |
There was a problem hiding this comment.
We also need to add "ord:alias" here (it's already in-use)
There was a problem hiding this comment.
Ok, separate PR or include it here?
4 participants
Summary
Adds support for Arazzo multi-step API workflows in ORD.
arazzo-v1on API ResourceresourceDefinitions— for workflows scoped to a single API.workflowCapability type witharazzo-v1capability definition — for workflows that span multiple APIs. Such capabilities SHOULD list every covered API inrelatedApiResources.ord:orchestratesrelationType — declares that the source resource (e.g. aworkflowCapability) orchestrates the target API Resource.Scheduled for the next patch release (1.16.4).