Figure out approach to API schema versions
pamelafox opened this issue · 1 comments
We should version the schema so that a client/backend can convey which version of the schema they support. For now, I've put a version number at the top of the doc, but none of the sample applications document what version they support.
Possibilities:
- Sample apps can describe in README what version of schema they use
- Sample apps can pass down a header like AI-Chat-App-Version: 2024-01-28
- Sample apps can pass down a field in both requests and responses.
I don't like the idea of putting the version in the URL or query parameter as I don't imagine applications supporting multiple versions. I just think they should have a way of communicating which version they were built with. Once there's a new version, old versions can be stored in the repo by their version name, with changelogs/diffs between them.
I'm also wary of overcomplicating the schema when we're not sure how generally useful it will be.
Closing this issue, since this repo is replaced by https://github.com/microsoft/ai-chat-protocol/ which has folders for each version of the spec.