Develop API versioning strategy

[slifty]

As we begin to make progress on generated SDK assets (see #497), we need to start to be intentional about communicating API changes that warrant that generation.

This is also important because third parties might generate clients -- we know at least one group uses our published OpenAPI spec to generate a Java client.

---

There is a distinction between API versioning (e.g. https://foo.api/v2) and versioning the swagger specification itself. This issue is intended to cover both questions.

[reefdog]

Relevant story: PhilanthropyDataCommons/meta#125

[slifty]

We met to discuss this last week, and I believe have a potential consensus on the following:

API Versioning

General Thoughts

Tomes have been written around API versioning strategies with strong arguments in many directions. Google has some good articles. There is a compelling philosophy that URL versioning (e.g. api.com/v1 and api.com/v2) is a misnomer (the google article basically argues those are two completely different APIs with no relationship with one another, as opposed to being "versions").

Under that view, the suggestion is that a more meaningful approach is to leverage HTTP headers to allow clients to signal the version of the content types they are expecting. This allows the server to leverage HTTP status codes to communicate whether or not those structures are supported.

This is a fine concept, and is one that an API project might consider implementing (indeed, some members of this team HAVE implemented that!).

That said, there are a few important truths to consider for this stage of the PDC:

1. We have not declared our API stable yet in the first place -- there is no version 1.
2. The only people using our service have a direct relationship with us -- we can communicate changes directly.
3. We are not planning to support more than one version (regardless of what "version" means here)

Given this, I'd like to propose that we do not version our API in its implementation. That is, we don't have a version in the URL, we don't have versions in returned objects, and we don't think about versioning of object types in headers.

Swagger Specification Versioning

But there's more to think about!

Our swagger specification is a document that third parties (including ourselves) will rely on to generate client libraries that work with our API. Those third parties need to know when something has changed in order to know when to generate a new client.

I would like to propose that we version our openapi.json using semver and even go so far as to:

1. Maintain a change log
2. Publish releases of that specification via github

To be clear I'm not suggesting that CI/CD rely on us tagging versions, etc -- that would stay fluid and maintain the "one merge => one deploy" approach. Rather, when the spec gets an updated version we would have CI publish a release of the openapi.json under the new version number (and eventually, publish a new version of whatever SDK we're generating, though the version number of the SDK would need to be... figured out some other way). That updated version could also be used by third parties to know when they need to trigger their own SDK build processes.

[jasonaowen]

I'd like to propose that we do not version our API in its implementation

I strongly agree with keeping our API versioning at 0.x and avoiding all the overhead content type versioning requires, for the reasons @slifty listed!

version our openapi.json using semver and ... Maintain a change log

Versioning the OpenAPI spec makes sense, as does maintaining a change log with a target audience of partner developers consuming our API (as opposed to the more user-facing change log in the front end). +1!

Side note that this will increase merge conflicts by making otherwise-unrelated API changes need to update openapi.json and the changelog, which I think is fine - they should be very small merge conflicts, and will hopefully encourage us to be more intentional about making API changes and recording them in the change log.

Publish releases of that specification via github

This would be a good thing to do, but it does require some engineering work to automate (or to do manually). Can we get by with just having the live version at https://github.com/PhilanthropyDataCommons/service/blob/main/src/openapi.json , plus the Swagger UI at https://api.philanthropydatacommons.org/?

and eventually, publish a new version of whatever SDK we're generating

Once we get here, then we'll definitely need CI and releases. Can we wait on releases until then, though?

[slifty]

Very happy to have releases hold until they're needed -- I think what I'd do is still make an issue for that concept to capture it, but we just don't scope it / put it as a "later" task.

[slifty]

I'm going to declare this closed since, well, we identified the strategy!

This will be referenced as we work on #497