Use relative URL in rest/sitemaps/events/subscribe or not ?

[lolodomo]

Originally declared in openHAB repo: openhab/openhab-distro#442

[lolodomo]

As I am fixing the sitemap SSE API at the moment to make it easily usable, it is certainly the right time to fix that issue too, even if it will break the API and require a little change in all API consumer to handle a relative or absolute path.

[lolodomo]

I have a doubt because absolute URLs are used in all the sitemap REST API. Why should it be a relative path only for one particular API ?

[lolodomo]

As there was no feedback, I assume using absolute path is expected.

[maggu2810]

Sorry, that you never received any comments.
I am not using the sitemap REST API myself, so I don't have a string meaning here.

WRT reverse proxies I would assume that URLs have to be relative to be resolved.

[lolodomo]

@maggu2810 @kaikreuzer : I played with the REST API and I discovered that absolute URLs are returned in several places:

• default GET / => filed "url"
• items GET /items => field "link"
• sitemaps GET /sitemaps => field "link"
• sitemaps POST /sitemaps/events/subscribe => field "location"

As you can see, this is not something specific to the sitemaps REST API. In particular, the items REST API has the same "philosophy".

So is it something to change ?
This would be certainly a major braking API change.

[maggu2810]

As written above, I would prefer relative URLs so it works for certain reverse proxy configurations, too.
I don't know why absolute URLs has been used.

Yes, this would be a really major API break.

[flaviocosta-net]

Hi @lolodomo, to make it short, it is either a matter of making it simpler for API clients. or for whoever is configuring the (proxy) servers.

Long answer: this "philosophy" issue is indeed a recurring discussion on REST API design. Many people do recommend an absolute URI to be returned to clients, for instance:
https://stackoverflow.com/questions/2239405/hateoas-absolute-or-relative-urls
http://restful-api-design.readthedocs.io/en/latest/urls.html

The second link gives the following reasoning for this choice:

It is strongly recommended that the URLs generated by the API should be absolute URLs.

The reason is mostly for ease of use by the client, so that it never has to find out the correct base URI for a resource, which is needed to interpret a relative URL. The URL RFC specifies the algorithm for determining a base URL, which is rather complex. One of the options for finding the base URL is to use the URL of the resource that was requested. Since a resource may appear under multiple URLs (for example, as part of a collection, or stand-alone), it would be a significant overhead to a client to remember where he retrieved a representation from. By using absolute URLs, this problem doesn’t present itself.

The Java URI implementation makes it relatively easy to resolve relative URLs, but that might not be the case for every client that might be using the ESH APIs. In any case, it requires some extra logic to be added on the client side.

On another hand, in the JSON API forum someone mentioned the following:

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.

This is exactly the issue that triggered the discussion on the openHAB forum. We either have people adjusting the configuration on their proxy servers to properly forward the host header, or we break the API and give clients the extra burden of resolving the URLs. Given that we have not more than a handful officially supported clients, but thousands of openHAB deployments behind different proxy setups, I would vote for changing the APIs and the clients. Still, that's a big decision that definitely needs to be discussed by the senior members here.