OAS Workflow

A dummy proposal

Alessandro Duminuco – aduminuc@cisco.com

Operations

• These are the operations already defined in OpenAPI, i.e. the actual API calls.
• They can be referred to by
• operationId: getUserByName
• operationRef: https://petstore3.swagger.io/api/v3/openapi.json#/paths/~1user~1{username}/get
• Operations define:
• Input parameters
• Request Body (POST/PUT)
• Responses

​

​

/user/{username}:

get:

tags:

- user

summary: Get user by user name

description: ''

operationId: getUserByName

parameters:

- name: username

in: path

description: 'The name that needs to be fetched.'

required: true

schema:

type: string

responses:

'200':

description: successful operation

content:

application/json:

schema:

$ref: '#/components/schemas/User'

'400':

description: Invalid username supplied

'404':

description: User not found`

Procedures

• A procedure defines a set of actions over one or more APIs to achieve an objective
• A procedure defines:
• a set of input parameters, simirarly to what an operation does
• An ordered list of steps, where each step represents a call to an operation or to another procedure.
• a set of outputs
• Each step describes:
• Which operation or procedure to call
• How to populate the input parameters
• Defines success conditions
• What to do on failure events

​

​

procedureID

parameters

steps

outputs

stepID

operationID/ProcedureID

parameters

Success/onFailure

stepID

operationID/ProcedureID

parameters

Success/onFailure

stepID

operationID/ProcedureID

parameters

Success

1

2

3

Operations

(existing in OpenAPI)

Procedures

procedureID

parameters

steps

outputs

procedureID

parameters

steps

outputs

Step ID within procedure

Reference to an operaton or another procedure

Reference to procedure input parameters

Success conditions and what to do on failure

Reference to procedure input parameters or previous steps outputs/responses

Reference to procedure input parameters or previous steps outputs/responses

Example based on PetStore (1)

userloginandretrieve:

summary: log in and retrieve a user

procedureID: userLoginAndRetrieve

description: Log in a user with a given username and password and then retrieve user details.

parameters:

- name: username

description: The user name for login

required: true

schema:

type: string

- name: password

description: The password for login in clear text

required: true

schema:

type: string

steps:

- stepId: loginStep

operationId: loginUser

description: Login user

parameters:

username: $parameters.username

password: $parameters.password

success:

- $response.code == 200

- stepId: getUserStep

oprationRef: https://petstore3.swagger.io/api/v3/openapi.json#/paths/~1user~1{username}/get

parameters:

username: $parameters.username

success:

- $response.code == 200

outputs:

user: $steps.getUserStep.responses.200

Example based on PetStore (2)

petpurchase:

summary: purchase a pet by name

procedureID: purchasePetByName

description: A procedure to pick and purchase a pet knowing its name

parameters:

- name: petName

description: Name of pet to purchase

required: true

schema:

type: string

- name: username

in: query

description: The user name for login

required: true

schema:

type: string

- name: password

in: query

description: The password for login in clear text

required: true

schema:

type: string

steps:

- stepId: getUserStep

procedureId: userLoginAndRetrieve

parameters:

username: $parameters.username

password: $parameters.password

success:

- $outputs.user.address is not None

onFailure: exit

- stepId: getPetStep

description: retrieve a Pet by Name

operationID: getPetByName

parameters:

petName: $parameters.petName

success:

- $response.code == 200

- $response.200.status == 'available'

onFailure: exit

- stepId: purchaseStep

description: place order

operationId: placeOrder

requestBody:

petId: $steps.getPetStep.responses.200.petID

address: $steps.getUserStep.outputs.user.address

success:

- $response.code == 200

- $response.200.status == "approved"

onFailure: retry

ouputs:

order: $steps.purchaseStep.responses.200