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)

[orubel]

@MikeRalphson API Chaining uses internal loopback for redirection so it can use a single request/response for every endpoint in the chain. You are confusing it with 'method chaining' which uses external redirection and requires generating a separate request/response for each endpoint and going outside the DMZ and coming back in each time.

API Chaining is a strictly internal process.

The main difference in the two is where the front controller is placed in the api backend; in single threaded api applications(REACTOR), this is in the web server thus making it only possible to do 'method chaining'... not 'api chaining(tm)'

[CodeFromAnywhere]

I've created a similar spec called ActionSchema which was built on top of JSON Schema, but the usecase and implementation are different I think. It's not tightly coupled to individual openapis, rather my documents live with clients and allow for chaining of multiple apis of multiple vendors/microservices.

To answer the question of the discussion, my primary usecase is tool use for AI agents. Agents need to be able to specify multiple APIs, hence it should be defined separate from an individual OpenAPI.

I just became aware of Arazzo and it seems like a great effort. I'm happy to discuss further if you have any feedback and/or questions!

[frankkilcommins]

@CodeFromAnywhere thanks for the information and your willingness to participate.

Arazzo too can describe workflows across multiple APIs (from multiple vendors) and we do expect use-cases where these will be leveraged by AI agents. It's feasible to expect many may well be client managed artefacts and be mashups of offerings from various providers, or lead to interesting marketplace type of offerings (e.g. search for your use-case/problem > discover the various workflows > see what vendors offer such capabilities and at what price > choose appropriately).

Seems like there could be sufficient overlaps and I'm interested to see if there are ways to collaborate and/or learn if there are gaps prohibiting your tooling from also leveraging Arazzo.

[orubel]

it actually fails horribly because it doesn't follow HTTP standard. An API endpoint can call another API endpoint using an internal redirect (aka loopback/forward) or via external redirect (aka round robin). You spec not only doesn't support redirects, it doesn't support internal redirects, checks on redirects (permissions, request params, etc)

The entire solution is half-assed, insecure and partial implementation

[CodeFromAnywhere]

@frankkilcommins I've started building ActionSchema.com which is a search engine for OpenAPIs. let's talk and see if we can have it generate/build Arazzo workflows as well. I think this idea is great!! I'll DM you on twitter and join the bi-weekly.

@orubel I've never heard about loopback/forward so I must be missing something. I aim to support anything that can be defined with OpenAPI. I haven't seen what they say about redirects so that's indeed interesting, some apis automatically follow redirects, some don't, and I think that's maybe up to the creator of the definition of the OpenAPI? Anyway, for me it's not that important, it's not very common these days.

[orubel]

@CodeFromAnywhere Just because YOU haven't heard of it, doesn't mean that it's not part of the HTTP standard and that the request/response can still act that way. The maintainers of OpenAPI have no say in the HTTP standard; redirection happens on the backend in the API (remember, the API is NOT the call... it is the backend where the call is HANDLED).

BTW... their is already a IETF standard for cataloguing apis for searching called api-catalog (https://datatracker.ietf.org/doc/draft-ietf-httpapi-api-catalog/). This enables ALL apis to be added to ANY search index (not just yours)

[orubel]

Ok so I have commented a bit but I wanted to make a documented statement (which will most likely get blocked)...

First, 'call flow' (for apis... specifically web apis) refers to the request/response call flow. Often people ONLY think of this in the context of a gateway/proxy these days but neglect to consider the HTTP STANDARD and how it supports internal redirection within the application (see loopback or forward vs redirect - http://www.javapractices.com/topic/TopicAction.do?Id=181) as well as external redirection.

As stated, this is NOT language specific. It is part of the HTTP STANDARD. (see https://www.rfc-editor.org/rfc/rfc9110.html#name-message-forwarding and https://www.rfc-editor.org/rfc/rfc9110.html#name-routing-inbound-requests)

Now... an api call can call another api two different ways:

• hardcoding the other api call to call via internal/external redirect
• dynamically sending/creating the other endpoint via an internal/external redirect: ie consider a call that goes to a function that then bases the secondary call on your existing JWT ROLE( if user, route this way, if admin route over there)

NOW... in an internal redirect, you have to do security checks INTERNALLY as internal loopbacks will never hit the gatewy otherwise you are allowing a security bypass (as the secondary api call will NEVER hit the gateway since you are forwarding internally within the app to another api endpoint).

If you are doing a EXTERNAL REDIRECT... not so much a problem. But if there is any level of dynamism in the application, where the redirected endpoint is based upon a value (if ROLE=='user' redirect here, if ROLE=='admin' redirect elsewhere), you now have a problem as you have to take into consideration programmatic communication or a level of dynamism/automation.

I have done all the above BUT automation lends itself to 'dynamism'... not hardcoding. The more you hardcode, the less you can automate.

So what you HAVE (and what you are creating) is a HARDCODED METHOD CHAIN VIA EXTERNAL REDIRECTION.

This can only allow for a one-to-one hardcoded relationship with ZERO dynamism and ONLY with external redirection.

That is the ONLY THING you CAN support. No other type of call flow from one endpoint to another can (or ever will) be supported.

As long as this is your acknowledged approach, this is fine

Thus, you are not using 'API Chaining(tm)'(which uses internal redirection)... you are using METHOD CHAINING (https://en.wikipedia.org/wiki/Method_chaining)

The two are starkly different as

• 'API Chaining(tm)' is dynamic and uses an internal loopback (aka forward)
• whereas method chaining is usually hardcoded and uses external redirect

This is the difference between a 'call flow' and what you are trying to do... which is create a hardcoded 'method chain'' in an external properties file with no dynamism in the controller/business logic (also see comment below about single threading/multithreading)

[orubel]

One other thing I just realized I should mention here while we are talking about HTTP call flow...

There are two main api patterns used in api applications (the application itself NOT 'design patterns'):

• proactor : use for multithreaded api apps
• reactor: used for single threaded api apps

These handle call flow ENTIRELY DIFFERENT!!!

Both have a 'front controller'(https://en.wikipedia.org/wiki/Front_controller) and use a web server.

"Front controllers are often used in web applications to implement workflows"

BUT...

• proactor puts front controller in the application to be IN COMPLIANCE with HTTP routing (internal AND external routing of the HTTP RESPONSE)
• reactor puts the 'front controller' in the web server and thus is OUT OF COMPLIANCE (thus only allowing for external routing via external redirect); apis cannot talk to other apis without a COMPLETE ROUND-ROBIN to dns/gateway/server and back in.

AWS gets around this mistep witha bandaid fix called 'STEP FUNCTIONS' which creates a secondary internal loop ALLOWING FOR INTERNAL REDIRECTION (I actuall brought this up to them during a consult in Aug of 2016 and 'Step Functions' were released by December of that year.)

Thus... call flow is ENTIRELY dependent on the type of pattern being implemented in your application.

Currently, it seems you are ONLY TARGETTING single-threaded applications with this iteration.

Its VERY Javascript/NodeJS oriented.

So in all, this is targetting:

• hardcoded 'method chain'' written in an external properties file (not 'api chaining(r)' which uses an internal loopback to share the request/response data)
• unable to support internal loopback (which is part of the HTTP standard)
• no dynamism in the controller/business logic; geared towards mixing business logic with 'model'/domain/resource
• and only supporting single threading applications as a result

[orubel]

One additional thing I would point out too which I added into 'API Chaining(tm)'; a long time ago which I was inspired by Link Relations...

Your current call flow is not 'relatable'; If your resource is HEIRARCHICAL or RELATIONAL; each endpoint is relatable to the next by the KEYS or INDEXES that they share with other RESOURCES/OBJECTS.

To think of it in the way of databases, FOREGN KEYS relate it to other TABLES enabling JOINS. Even in a CACHE, INDEXES can allow the same thing. This is what ENABLES the 'callflow' in the first place.

You spend alot of time creating call flows by HAND but at no time does it create ways for the end user to 'dynamically' create them based on their ROLE.(RBAC/ABAC); Keep in mind, endpoints are accessible using the ROLES stored in the JWT tokens so while they may have access to the first endpoint in the call flow, the second may be rejected because they don't have the proper permissions.

This is why it is easier to dynamically generate a 'tree' (based on their ROLE), that they can create call flow from. This is effectively how I have built 'api chaining(tm)'... but it require an internal loopback/redirect.

Without the internal loopback, you are using a separate REQUEST/RESPONSE for each separate api call in the chain as it has to do an external redirect. An external redirect does the following:

• drops the threads/workers after initial endpoint call and releases their resources (which by default is 60 seconds in most cases)
• make a external redirect by going outside the DMZ
• comes back in via router/DNS
• reissues request/response at the proxy/gateway/server and reassociates the client session
• has to reparse and run checks all over again

Additionally, because you are hitting DNS with 'method chaining', you increase security risk of interception from listeners/spoofers/etc. The reason being is because the HTTPS is mainly handled at the LOAD BALANCER and the HTTP is sent to the app server/web server to speed traffic BUT when you send a redirect... you have to be careful to use a HTTPS tunnel even though one was not sent. ;)

This will trip people up. Meaning all external redirection will have to ENFORCE HTTPS... again adding to the overhead/latency.The load balancer can send via HTTP to the web/app server as long as in exists on the same VPC/VPN but send externally, you will have to use HTTPS to avoid interception.

With an internal loopback, it uses existing checks and security already run thus :

• low processing : checks on run once on initial request/response and request/response is shared with each internal loopback
• no latency : as request/response does not leave application, there is not network latency
• no potential security risk (by keeping request/response strictly internal to the api app) : again as request/response does not leave application, there is no security risk.

You can still make this dynamic but you can't target BOTH REACTOR PATTERN(single threaded) and PROACTOR PATTERN(multithreaded)... and using external redirect will always be slow and insecure.