Should our API versioning for the 3 APIs in CDS be independent or a single version of the data spec?

[michael-danko-passport]

Is your feature request related to a problem? Please describe.

With the recent initial release of CDS, each of our 3 CDS APIs are currently aligned to be version 1.0. As we consider additional changes to the specification, do we plan to release CDS as a collective version or will each of the CDS APIs be released as individual versions?

Describe the solution you'd like

I see two options with pros/cons for each approach:

1 version number for CDS that applies to all of the APIs

• Pro - It could be easier to bundle up changes and seek approval from all stakeholders.
• Con - A change in one API (Curb) with no change in another API (Event) would mean that Event is incremented in versions. This could be difficult to track version compatibility long-term for API consumers.

1 version number for each of the CDS APIs

• Pro - API development can occur independently without impacting compatibility for other APIs.
• Con - Branch management for specs and different versions could be more difficult.

Impacted Specs

• Curbs
• Events
• Metrics

[michael-danko-passport]

@schnuerle I could see this impacting how we want to structure the OAS files within Stoplight and different branches. I opened this to be a talking point for a future CDS WGSC meeting if we can add it to an upcoming agenda.

[schnuerle]

I think option 1 is the way to go, like we do with MDS, for a few reasons.

Our 'APIs' are really just organizational units to group endpoints into understandable chunks. So for example we have 'Curbs' which includes 'Endpoint: /curbs/zones' and 'Endpoint: /curbs/policies'. But we could have made a 'Curbs' API that included /zones and /places/ and /areas, and another 'Policy' API that included /policies. So if we are talking about versioning, I'd say endpoints are the granular level.

Even so, there's more to the spec than just the 3 API folders/endpoints. There is also the general information page which affects all APIs, and the home page and other areas like the data source operators. We'd have to version these as a whole. And any new APIs we create (MDS started with 3 and now has 6).

What we've seen with MDS is releases usually have some kind of changes in all API areas or common areas. You can see some release notes here, with changes broken out by API. Many times a change in one API will impact how it's referenced in another API, or a general change will impact all or most APIs.

Even if there isn't much or any change to an API in a release, keeping all the parts of CDS in sync I think it best practice and typical with data specs and software releases. For example, your Apple iPhone has updates, but not all default apps are touched each release, but are bundled anyway. Third party apps are versioned separately, and this would be the equivalent of applications, services or dashboard based off of CDS. Apple Watch has separate versions, but this is more equivalent to MDS as an analogy. In any case, we do have a mechanism to make small patches and and changes to releases (eg, we had version 1.1.1 of MDS) and that can still be used in with CDS.

Each release also goes through a rigorous approval process defined by our bylaws, which takes usually 1-2 months of coordination, meetings, documentation, and approvals. It's a good governance process that ensures privacy, technology, strategy, and board reviews happen with both public and private sector members. Doing this for each API would I think be too cumbersome.

The way releases work in GitHub, all changes in a repository are bundled into a release. So if we did want to have each API and the base of CDS as their own releases, then each would need to go into their own repos. I believe that would add to complexity and understanding.

We'd also need to consider which versions of which APIs work with which versions of the other APIs. Hypothetically, v1.2 of Curbs might only work well with v1.0, v1.4 and v 1.8 of Events for some valid reasons, but not v1.9 or v2.0 of Events. Documenting that might be tricky or confusing.

Unless we can enumerate some key benefits to versioning each API, then I think we need to keep it as versioning the CDS release as a whole.

[michael-danko-passport]

@schnuerle Those are some great considerations so thank you for sharing them.

As we look at how API publishers and consumers will manage the technical systems that interact with these schemas, a side effect of a single version for all specs is that time/technical resources will be spent on making potentially unnecessary changes to the API versions.

I understand that our CDS versioning guidelines outline that the header of requests should contain a custom Accept header in this format:Accept: application/vnd.cds+json;version=1.2.0. If we look at each of the 3 CDS APIs (Curb, Event, Metric) being 3 different resources, technical efforts will need to be spent updating each resource when there may not be any true updates needed.

Additionally, there will also be the additional overhead to maintain new Open API Spec (OAS) files and the documentation to support each version for our APIs. A patch of the Curb API could increment v1.0.0 -> v1.0.1 and there would be a need to create and review the OAS for both the Curb, Event, and Metric APIs. As CDS matures, multiple "versions" would represent the same technical contract between systems and is one of the benefits of the major.minor.patch semantic versioning that CDS has adopted.

While I can't speak to all of the administrative processes that are needed to review and approve updates, I think it would be beneficial for the WG to consider if avoiding any additional overhead comes at a cost of making CDS more difficult to adopt.

[michael-danko-passport]

@schnuerle I believe we can close this since we landed on the idea of versions being the same across each APIs and that influenced our decision to use individual branches to store the information and display it within Stoplight.

Do we have a formal process for closing out issue discussions on Github?