OAI / OAI/Arazzo-Specification
Can we simplify a set of inputs automatically applying to headers/payload/etc?
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 471
- Forks
- 69
- Avg merge
- 17h 58m
- Merged PRs (30d)
- 19
Description
So per the discussion on dependsOn(https://github.com/OAI/sig-workflows/issues/153) and the potential notion of a workflow scoped dependsOn, it got me thinking. In the case of most APIs, they often need authorization of some form. Because this is such a common thing for most APIs, it seems a bit redundant that even if we remove step dependsOn and have workflows dependsOn, that every single step will need to set the Authorization header. For example: (https://github.com/OAI/sig-workflows/blob/main/examples/1.0.0/LoginAndRetrievePets.workflow.yaml). The first step is the auth step. The second pulls the auth response token and sets it in a header (Authorization). For a workflow with 50 steps, this is duplicated in every step.
In OpenAPI spec, you can define a set of query options before the methods:
paths:
/: # Root path
parameters:
- $ref: '#/components/parameters/filter' # Common filter parameter
- $ref: '#/components/parameters/page' # Common pagination parameter
get:
summary: List resources
description: Retrieve a list of available resources.
responses:
'200':
description: Successful resource retrieval
In the smidge of a snippet, the root path defines the two query params, that are then automatically assumed as part of every operation including child path operations. There is no need to repeat the declarations for each operation.
Thus, I think something similar should be allowed so that various workflow steps don't have to keep duplicating the same headers, etc. Naturally they CAN do so, but if workflow scoped parameters are provided, they should be automatically part of every step. I would add though that there should be a way to "remove" them per step if desired. For example, a workflow with steps that cross different API surfaces, where a step may hit a public API that doesn't need an Authorization header (and having one could affect the request for some reason lets say).. that step should be able to "block" or "remove" those workflow scoped parameters so that tooling can properly NOT generate code/docs/etc for those.
This may tie in to what Roman was partly discussing in (https://github.com/OAI/sig-workflows/pull/155) though I am not sure how that became a pull request instead of an issue that we discuss? Maybe there was a discussion on this I missed?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review examples/1.0.0/LoginAndRetrievePets.workflow.yaml and the dependsOn discussion in issue 153, then compare the proposal with OpenAPI path-level parameters. Define the workflow-scoped inheritance and per-step removal behavior, including how tooling should represent it; done means the specification rules and examples are agreed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100