-
Notifications
You must be signed in to change notification settings - Fork 2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Develop API versioning strategy #524
Comments
Relevant story: PhilanthropyDataCommons/meta#125 |
We met to discuss this last week, and I believe have a potential consensus on the following: API VersioningGeneral ThoughtsTomes 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. 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:
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 VersioningBut 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:
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 |
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!
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
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/?
Once we get here, then we'll definitely need CI and releases. Can we wait on releases until then, though? |
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. |
I'm going to declare this closed since, well, we identified the strategy! This will be referenced as we work on #497 |
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.The text was updated successfully, but these errors were encountered: