Operations in version specs should be additive over time

[cmars]

We found that carrying prior versions' paths forward and copying them into the next version to be cumbersome, brittle, and error prone.

Instead of requiring each version release to re-declare and re-enumerate all its operations, operations should be deprecated by newer versions if re-declared; otherwise, the older release should still resolve until deprecated and sunset.

Scenario

To illustrate how this should work:

Initial version of a resource "things" is released as things/2021-08-20/spec.yaml, which declares:

paths:
  '/things/{id}':
    get: {...}
  '/things:
    get: {...}

Following version of things, things/2021-09-30/spec.yaml declares:

paths:
  '/things/{id}':
    delete: {...}

Current interpretation

The current implementation sees each version spec as a standalone contract defining the resource. So, it basically interprets this as: "on 2021-09-30, two GET operations were removed and a DELETE operation was added". Ok, that might be precise enough for machines, but it makes things a lot harder on developers; you have to remember to copy over each operation, hopefully you get it right, and if you don't, users of the latest API at that stability will be in for an unpleasant surprise.

Proposed interpretation

Proposal here is to change the interpretation to: "on 2021-09-30, a new DELETE operation was added". It doesn't "erase" the prior GETs; at 2021-09-30, those operations (path + method) still resolve to the 2021-08-20 versions.

Solution

The only thing that changes here is how resource versions are compiled. The resulting output for the effective API versions:

2021-08-20/spec.yaml:

paths:
  /things:
    get: {...}
  /things/{id}:
    get: {...}

2021-09-30/spec.yaml:

paths:
  /things:
    get: {...}
  /things/{id}:
    get: {...}
    delete: {...}

Implications

Existing usage

Existing resources that were re-declaring their prior operations across versions will not need to change anything; they will not need to do this anymore in future releases, once upgrading to this change.

Explicit operation sunsetting

In cases where an operation (path + method) needs to be removed, this deprecation and sunsetting process will need to be made explicit. A followup issue will propose how that should work.

Release version

Because this is a pretty fundamental change in output, this change should be released as a major version bump (2.0.0).

[cmars]

The only thing that changes here is how resource versions are compiled.

To better clarify this point, what really changes is the implementation of ResourceVersions.At. Instead of returning the snapshot spec at a particular version, this method would get updated to return a cumulative spec across all versions, containing the most recent non-sunset version of each operation.