Versions are specified by the url.
Commitment on backwards compatibility
We are committed to maintaining backwards compatibility in our API. To support this, we will not make breaking changes within an API version.
Changes allowed within a version
| Accepted changes | Notes |
|---|---|
| Adding *new endpoints/resources | - |
| Adding optional parameters to existing endpoints | - |
| Adding new fields to existing resource responses | Clients should not use strict mode in their parsers, and should not assume that any keys not currently in the response will not be added later. |
| Changing order of fields in existing responses | Clients should not rely on ordering of fields within a response object. |
| Changing the length/format of ID fields, or other opaque strings | IDs of individual objects will not change, but the format may be different between objects. Clients should not introspect on the values of IDs. Thus, should not base logic on comparing/computing their values. |
| Adding new options for "enumerated" fields | For example, adding a new facility type |