API versioning and deprecation
How the Web Access API changes, what counts as breaking, and how an endpoint or field is deprecated before it is removed.
The Web Access API uses the /v1 path prefix for HTTPS requests at https://request.usestring.ai/v1 and browser
WebSocket connections at wss://request.usestring.ai/v1/wss. A version only gains things. A change that can break code
written against it ships under a new version instead.
What can change in a version
| Change | Examples | Breaking |
|---|---|---|
| Additive | A new endpoint; a new response field; a new optional request field; a new value in an enum or error code. | No |
| Breaking | An endpoint or field removed, renamed or retyped; a new required request field; input that used to be accepted now rejected. | Yes |
Ignore response fields you don't recognise rather than rejecting them, and give a switch over an enum a default case.
Deprecation
When we plan to remove an endpoint, a field or a version, we mark it deprecated in the
OpenAPI spec and on its docs page, naming the replacement and the removal
date. Until that date the deprecated endpoint or field keeps working as documented. After it, requests to a removed
endpoint return 404.