Proposal for incorporating state transition into Open API

[ptoora]

Hello, I believe that some ideas around this have already been expressed, but I'm coming at this from a QE approach. A typical application will have three components:

1. behaviour
2. contract integration between behaviour units (internal or third party)
3. state transitions

Behaviour is expressed in Acceptance Criteria and implemented as code. OpenAPI beautifully handles contract integration. What is missing is how we define (outside of behaviour) state transitions, relationships/flows between API end-points and resulting state change. If we could extend OpenApi to include the expressions of relationships between end-points (HATEOAS like) and the resulting state transitions, this would simply application build, as much more would be done declaratively, and would help with Contract testing serving Continuous Delivery. Consumer functional tests would use a stub provided by the service owner (e.g. in Wiremock) that enforced the contract and state expressed in OpenAPI

[darrelmiller]

@ptoora Just out of curiosity, have you looked at Link objects in the v3 spec?

[kephas]

The Link section says:

Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response.

This seems contradictory with REST, and specifically with HATEOAS, where the content of the runtime response should contain hypermedia links that are used to drive state transitions.

[handrews]

@kephas There are two ways to look at this apparent mismatch:

1. As a design-time system geared towards generating out-of-band (but synchronized to a source of truth) documentation and code, OpenAPI will never entirely match REST philosophy (I say this as someone who believes that HATEOAS is achievable and worthwhile, and has written a more than a decade old HATEOAS client that is still used in production long after I left the company)
2. If one thinks of OpenAPI Descriptions as describing the potential state transitions, rather than guaranteeing that every transition is valid at runtime, then we can start to see how it can bridge the HATEOAS and static paradigms

Either way, any real change here to make this bridging more clear and elegant would be too big for the 3.x line, so this would be part of Moonwalk (4.0).

[kephas]

I don't understand how there should be a mismatch between REST and OpenAPI. Roy Fielding's dissertation is very clear that the semantics of the representation of a resource is dictated by its media type.

OpenAPI could be used to describe the format of each representation and, for each possible state transition, many informations could be provided:

• the media types acceptable for the body of the request (and their format)
• the type of resource designated by the state transition
• the media types that can be used as response body (for methods like POST and DELETE, whose response body is not a representation of the resource)

All of those informations are supposed to be out of band in REST, so OpenAPI could be the vehicle for those. And the way OpenAPI currently describes request and response bodies is perfectly usable here too.

[handrews]

This scale of change is best discussed in Moonwalk (and can be backported if relevant and we decide to keep the 3.x line going). Closing in favor of:

• OAI/sig-moonwalk#30
• OAI/sig-moonwalk#58