I’ve seen examples of both relative and absolute links in the specification. Can either be used, and is there any recommendation for the use of one over the other? Can/Should they be used interchangably within an API (for whatever reason), or should consistency be favoured?
For maximal compatibility, use aboslute URIs.
(See discussion in https://github.com/json-api/json-api/issues/898.)
Crafting absolute URLs can become a challenge when your software is deployable on-premise behind some customer specific HTTP infrastructure, e.g. SSL terminators, load balancers and in some cases web servers. Getting the original HTTPS domain used for the client facing SSL termination requires tunneling the original host through possibly many components in the upstream HTTP stack (typically in the
X-Forwarded-Host header unless the
Host header can be sent through unchanged).
For that reason, we are using root-relative in our responses, e.g. starts with /. I wouldn’t mix both, though. If you choose relative, use it everywhere.
If we were providing an API at a consistent domain, we’d be using absolute URLs everywhere.