KA: API Versioning

[cmgrulke]

We need knowledge acquisition regarding the patterns for API versioning and maintaining backward compatibility to previous API versions So that an implementation path can be well considered when changes to the API occur and backward compatibility is needed

I need to ensure backward compatibility can be maintained if the API structure migrates forward (e.g., new attributes are added or complexity of a resource and its relationships increases). Ideally, older API versions would provide access to the latest data, but shoved into the old API format when changes occur.

Acceptance Criteria: Teach everyone on the team about the options

[jtumkur]

• Deploy in ChemReg with the version API versioning

• Copy the old database for old API backward compatibility

• Version in URL is what we should maintain as standard

• Complex routing

• Versions and across the teams

We can talk to Terry about this as well.

[tbnorth]

@jtumkur - Terry probably won't see these things unless you tag @tbnorth, not sure why I looked at this one :)

• How often will the API change
  • Every few years, once a year...?
  • I've seen things like http://example.com/api/v3/... which I guess could extend to .../v3.7/...
• What's considered a breaking change
  • adding attributes to JSON usually doesn't break things backwards, but newer consumers might want to ensure the new attributes are present.

[cmgrulke]

Thanks @tbnorth, but the question here is whether or not someone within the EPA has already done thorough research and designed the API versioning system that is most appropriate for our use cases. Science changes. ChemReg is intended to act as a chemical hub with multiple application interacting with its API. While limiting major changes to ChemReg to reduce the need for versioning is valid, to prevent stagnation of the application, flexibility in the json is going to be required (just like in database schemas). I personally like the use of media type to support API resource versioning, but what we need is either that a decision has been made and documented by SCDCD or this team should do that design so we are prepared to manage change.

[tbnorth]

I see, @cmgrulke. I vaguely remember an OSIM presentation about API design a few years back, don't remember if it covered versioning. If EPA has any such thing, would hope that Asif would know about it, will ping him.

[tbnorth]

A non-chem. EPA API project, fwiw: https://www.epa.gov/ceam/hydrologic-micro-services-hms

[jtumkur]

• Common integrated API versioning.
• EPA feedback needed for standardization.