Table of Contents
All current APIs are prefixed with:
RackHD extenders can supplement the central API (common) with versioned customer-specific APIs in parallel.
Use the following convention when referencing API version:
/api/current/... /api/1.1/... /api/2.0/...
The second /[…]/ block in the URI is the version number. The “current” or “latest” placeholder points to the latest version of the API in the system.
Multiple API versions can be added in parallel. Use N, N-1, N-2, etc. as the naming convention.
All API versioning information should be conveyed in HTTP headers.
A translation and validation chain is used to support versioned “types” for URI resources from the RackHD system. The chain flow is:
BUSINESS OBJECT — TRANSLATE — VALIDATE
Data objects should be versioned in line with the API version.
Use the following guide lines when determining if a new API version is needed.
The following changes require a new API version:
- changing the semantic meaning of a URI route
- removing a URI route
The following changes do not require a new API version:
- adding an entirely new URI route
- changing the query parameters (pagination, filtering, etc.) accepted by the URI route
- changing the return values on error conditions
- changing the data structure for a resource at a given URI