OAI / OAI/Arazzo-Specification

Can we simplify a set of inputs automatically applying to headers/payload/etc?

Open
#157 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.