As APIs evolve due to changing software requirements, it becomes necessary to version them so as to not break consumers' usage. This specification defines how API versions are specified for APIs built at RentPath and how requests not conforming to this specification are to be handled.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF RFC 2119.
APIs will be versioned using the following two strategies:
- Accept Header
- Query Param
The accept header is the preferred method of specifying an API version.
The value of the Accept header should be as follows:
application/vnd.rentpath.api+json;version=<version number>
This is the preferred method for specifying an API version
A version is specified by a query param using the following syntax:
?api-version=<version number>
A request that specifies a version in both the header and a query param SHALL receive a 400 Bad Request status code and MAY receive a message indicating why the request was not accepted.
Request not specifying a version SHALL receive a response with a 406 Not Acceptable status code and MAY receive a message indicating why the request was not accepted.