We want to evolve the API without unnecessary versioning. To be able to do that, the consumer should

If the common storage type has to be changed (for example from string to int), a migration of content is perfomed together with any necessary update of the mapping code

With a well-defined versioning strategy, when releasing a non-backwards compatible version, you can keep the existing one and the new one working in parallel for a pre-defined window of time

you will need to accommodate backwards compatibility or support multiple versions of an API running in parallel

GraphQL APIs should prefer evolution over versioning, but overall, nobody has an absolute opinion about either approach

Pragma::Migration is an experiment at implementing Stripe-style API versioning.

The key thing about the REST approach is that the server addresses the client state transitions. The state of the client is almost totally driven by the server and, for this reason, discussions on API versioning make little sense, too. All that a client should know about a RESTful interface should be the entry point. The rest should come from the interpretation of server responses.

Adapters are strictly versioned: any change to an adapter interface - associative or not - is considered breaking and will cause a major version update of the component.

In the future, these attributes may expand without the API being versioned. The current attributes are: