We are asking the community to help us document use cases for API workfows

[namdeirf]

At the April 13, 2022 meeting of the SIG-Workflow Steering Committee, it was requested that the community share Use Cases of workflows to consider for the initial draft proposal (here).

Please provide examples and considerations in this discussion thread, please provide as much information as possible to help guide the discussions.

[asbjornu]

I welcome the idea of being able to describe workflows as an alternative to paths in an API. However, with the current proposal, I'm a bit unsure about who the intended consumers of the specification are.

If the intended use case is primarily to define how the server-side works and how automated tests and such can verify its behavior, then I think the current direction is great. However, if the intention is that clients are supposed to hard-code every expectation described in workflows, and especially with details like those described in #46, I fear that we might end up with tightly coupled clients which end up brittle and unable to handle changes in the server.

My use case of workflows would be to provide a more HATEOAS-compatible way to describe an API than what paths allows for today. I would like to describe which possible requests and responses (in terms of schemas and/or media types) a client might stumble upon in its interaction with an API, without a tight coupling between each individual request and response.

Allowing for such loose coupling between request URI, request body and response would give the server the ability to change the order of requests and responses, as well as which URIs the client should interact with, without the client having to change a single thing. This would allow for the client to become truly stateless and event-driven, only reacting to the responses it receives from the server and performing the next possible requests as described in the response. This would make the client more robust.

What I would like hardcoded in the client are only the names of possible workflows (currently named workflowId) and the schemas of the different requests and responses that might occur. When receiving a response, the client should only have to look for a known workflowId and execute the described request according to its inputs.

There's still one more level of decoupling possible here by making inputs dynamic in the response as well, but I feel like that might be wishing for too much. The ability to decouple paths, requests, and responses would be a huge step in the right direction, imho.

[handrews]

My use case of workflows would be to provide a more HATEOAS-compatible way to describe an API than what paths allows for today. I would like to describe which possible requests and responses (in terms of schemas and/or media types) a client might stumble upon in its interaction with an API, without a tight coupling between each individual request and response.

Strong yes to this. When I experimented with workflow-like API descriptions at a past job (which I left before really developing the idea) this was the goal.

At a previous job I'd developed a generic API client which had a follow() method to follow links (which we called "relations") and execute() method to perform operations (which we called "inks" because... I honestly can't remember anymore, I guess it made sense at the time). This worked very well, and largely removed the need to know what paths were involved. It was very heavily used internally, and as the basis for customer SDKs. The code was primarily coupled to the "relation"/link and "link"/operation names, plus the "link"/operation interfaces defined by schemas, and not to the paths.

What was missing in that system was a clear way to inform the client of meaningful sequences of follow() and execute() calls, as well as a system like OAS's runtime expressions to map the results of a previous GET into a subsequent operation request body or headers (although URI Template variables did get mapped from the previous GET response, IIRC- it's been quite a few years). I later tried to expand on this with JSON Hyper-Schema draft-07, but despite some initial excitement that never really got off the ground.

I have not had the time to keep up with the workflows SIG, but my hope would be that it would facilitate generic clients that similarly abstracted away path knowledge, but added information reducing the need to know the individual "relations"/links to follow and "links"/operations to execute.

[frankkilcommins]

@asbjornu Thank you for providing the use case, thoughts and feedback.

If the intended use case is primarily to define how the server-side works and how automated tests and such can verify its behavior, then I think the current direction is great.

This is indeed one of the primary use-cases in so far as being able to assert that the provider does what they advertise (validated by provider or by a higher authority). Additionally, the human readable aspects of workflows provide up front ability to a consumer to aid the assertion of whether or not a given API solves the consumer problem.

However, if the intention is that clients are supposed to hard-code every expectation described in workflows, and especially with details like those described in #46, I fear that we might end up with tightly coupled clients which end up brittle and unable to handle changes in the server.

Targeted SDK generation is also being discussed and we see advantages compared to generation automatically off an referenced OpenAPI/AsyncAPI document as paths/components not in scope for a given workflow can be ignored and reduce bloat of the generated SDK. Regarding the level of details described we keep it relatively simplistic regarding the order of step execution, what determines a success/failure, and some simplistic branching capabilities. If an API supported HATEOAS then I agree the underlying API responses should drive the client rather than the workflow itself which should be regarding a more static map as to what’s possible. I'm more or less expecting that we'll ignore #46 for the initial draft and learn from broader feedback as to a sensible next step.

My use case of workflows would be to provide a more HATEOAS-compatible way to describe an API than what paths allows for today. I would like to describe which possible requests and responses (in terms of schemas and/or media types) a client might stumble upon in its interaction with an API, without a tight coupling between each individual request and response.
Allowing for such loose coupling between request URI, request body and response would give the server the ability to change the order of requests and responses, as well as which URIs the client should interact with, without the client having to change a single thing. This would allow for the client to become truly stateless and event-driven, only reacting to the responses it receives from the server and performing the next possible requests as described in the response. This would make the client more robust.

This is interesting and something I’d like to explore more. As part of our initial mandate, we’re looking to take a step in the right direction compared to where much of the industry sits today with APIs that are described using OpenAPI (and not achieving HATEOAS).

[MikeRalphson]

(I will expand on these on Monday but wanted to get some notes down.)

The use-cases I have considered so far are:

• API portal onboarding - low time to first 200 OK
• Happy path testing of call flows
• Negative testing of error state transitions
• API Chaining (™ 😉) - Handing off from one API definition / microservice to another
• Passing a workflow from one application to another (security testing / debugging / fuzzing / ETL)
• Rich client SDK generation (flow based not endpoint based)
• Rolling up an API definition into one or more workflows, in order to reimplement important functionality without having to replicate the paths/operations exactly

[MikeRalphson]

Ping @abunuwas for your input

[frankkilcommins]

(I will expand on these on Monday but wanted to get some notes down.)

The use-cases I have considered so far are:

• API portal onboarding - low time to first 200 OK
• Happy path testing of call flows
• Negative testing of error state transitions
• API Chaining (™ 😉) - Handing off from one API definition / microservice to another
• Passing a workflow from one application to another (security testing / debugging / fuzzing / ETL)
• Rich client SDK generation (flow based not endpoint based)
• Rolling up an API definition into one or more workflows, in order to reimplement important functionality without having to replicate the paths/operations exactly

@MikeRalphson I can confirm that these use-cases have indeed been part of the set being discussed by the working group.

Related to these we've also been discussing:

• Provide deterministic recipe for use of APIs
• Improve regulatory checks (where applicable) via assertable workflows
• Ability to describe use-case where workflows span more than one API definition
• Overlapping on your SDK generation, we also see an ability to generate specific fit for purpose SDKs and ignore bloat from endpoints not relevant for the workflows of interest
• General DX and API documentation improvements and reducing the practice of out-of-band documentation sharing in addition to API definition documents
• Graphically render workflows to improve human understanding of how to consume API endpoints to achieve a goal (related to improved DX above)