4 ms·

Harded-coded URLs represent a larger API surface area. Hypermedia-driven APIs eg: HATEOAS permit the server to view URLs as an implementation detail. Some peopl

Harded-coded URLs represent a larger API surface area. Hypermedia-driven APIs eg: HATEOAS permit the server to view URLs as an implementation detail. Some people and some problems benefit from APIs with large surface area. Some people and problems benefit from APIs with small surface area. I tend to like APIs with small surface areas because it means I don't have to drag along outdated endpoints across minor versions because the org doesn't want to v2 anything. URLs as an implementation detail makes backwards compatibility much easier. So many times it's been useful to combine or split endpoints as the business needs change without affecting clients. The worst part about using HATEOAS for me has been clients who are used to constructing URLs continue to do so and create a ticket where the obvious first question is "Are you constructing that URL?"

PeterisP 5y ago
Even if the client fetches the URL dynamically, nothing about the semantics of that URL parameters or results can change or the client will break, you can only add extra optional things that the old clients will ignore. All those URLs still very much are part of the API surface area even if they're not hardcoded - their functionality still needs to have out-of-bounds documentation (contrary to the HATEOAS assumptions - "self-descriptive messages" IMHO can work only for syntax but are an unrealistic goal as far as semantics is concerned) and fixed behavior to match that documentation, in all realistic cases the client can't properly interpret the data without programmer intervention if the model changes. So this gives you only the freedom to change the URL naming scheme, but if you want to change the functionality in any way that's not 100% compatible, you still have to drag along outdated endpoints with the old functionality or you'll break clients. But this goes so much in contrast to your comment that it seems that I'm probably misunderstanding you - can you give an illustrative example on how exactly does this allow you to combine or split endpoints without affecting client software that sends/takes data from those endpoints and does some action (business logic) based on that data?
Joker_vD 5y ago
And another take on why clients being able to manually craft URLs is bad design: [0]. But prohibitting clients from manually constructing URLs really is not that hard: [1]. [1] https://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls/ https://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-h... [2] https://blog.ploeh.dk/2020/10/26/fit-urls/ https://blog.ploeh.dk/2020/10/26/fit-urls/
- Udik 5y ago
  From [1] > In the future, I plan to make URLs opaque when building level 3 APIs. Instead of http://foo.ploeh.dk/customers/1234/orders http://foo.ploeh.dk/customers/1234/orders, I'm going to make it http://foo.ploeh.dk/DC884298C70C41798ABE9052DC69CAEE http://foo.ploeh.dk/DC884298C70C41798ABE9052DC69CAEE .... Obviously, that means that my API will have to maintain some sort of two-way lookup table that can map DC884298C70C41798ABE9052DC69CAEE to a request for customer 1234's orders I pity the people who had to work with him, and the many thousands of hours this has probably ended up costing.
  - Joker_vD 5y ago
    Oh yeah, having a table with UUIDs instead of customer numbers for primary keys does waste many thousands of hours, that's why CQRS is also a terrible idea.
goto11 5y ago
URLs are not supposed to change since a URL identifies a resource. It is weird arguing for HATEOS as a mitigation for breaking a more fundamental constraint of REST.
- Joker_vD 5y ago
  > URLs are not supposed to change since a URL identifies a resource Strictly speaking, you're wrong: a URL specifies a location of the resource, and a mechanism for retrieving it. If the location of the resource changes, so would a URL. Even without this philosophical argument, there is an actual practical issue that URLs do change all the time. Both HATEOAS and Persistent URLs are mechanisms to cope with that: HATEOAS proposes to write clients that instead of using hardcoded URLs would use late-bound URLs supplied by the origin server; PURL proposes to hide the origin server behind a proxy that would translate hardcoded URLs used by the clients to the current scheme and either proxy or redirect the requests. The main problem with either solution is that URLs use domain names as their "authority" part, so whenever you lose control of the old domain, the "entry point" URL has to change and there is nothing much you can do about it. Yes, I know that URLs (URNs, actually, IIRC) were supposed to be immutable and eternal, with redirects set up (and maintained somehow, by someone, forever) to point to the current locations, but that didn't work out for obvious reasons.
  - goto11 5y ago
    Well if the API moves to a different domain name, HATEOAS will not help you one wit. You still need to hardcode the entry point. I still don't see any reasonable scenario where an API would change the (site-relative) URL's without also changing the semantics of the API. And if the semantics change you would have to rewrite the client anyway. In any case, if you change the URL's without changing the semantics you should respond 301 on the old URL, so even a client with hardcoded URL's would work correctly without the need for HATEOAS.
slver 5y ago
Do you realize that without “constructing a url” you need to go through few roundtrips just to find the resource url you actually need? You force your users through garbage you get support tickets like that. Instead of blaming the users, think why your great approach is actually problematic for them. The single entry point has no benefits unless the api is multi-company, no one specifically hosts it. Is this the case? If no, your hateoas and single url approach is pure cargo cult.

PeterisP 5y ago

Even if the client fetches the URL dynamically, nothing about the semantics of that URL parameters or results can change or the client will break, you can only add extra optional things that the old clients will ignore. All those URLs still very much are part of the API surface area even if they're not hardcoded - their functionality still needs to have out-of-bounds documentation (contrary to the HATEOAS assumptions - "self-descriptive messages" IMHO can work only for syntax but are an unrealistic goal as far as semantics is concerned) and fixed behavior to match that documentation, in all realistic cases the client can't properly interpret the data without programmer intervention if the model changes. So this gives you only the freedom to change the URL naming scheme, but if you want to change the functionality in any way that's not 100% compatible, you still have to drag along outdated endpoints with the old functionality or you'll break clients. But this goes so much in contrast to your comment that it seems that I'm probably misunderstanding you - can you give an illustrative example on how exactly does this allow you to combine or split endpoints without affecting client software that sends/takes data from those endpoints and does some action (business logic) based on that data?

Joker_vD 5y ago

And another take on why clients being able to manually craft URLs is bad design: [0]. But prohibitting clients from manually constructing URLs really is not that hard: [1]. [1] https://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls/ https://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-h... [2] https://blog.ploeh.dk/2020/10/26/fit-urls/ https://blog.ploeh.dk/2020/10/26/fit-urls/

Udik 5y ago
From [1] > In the future, I plan to make URLs opaque when building level 3 APIs. Instead of http://foo.ploeh.dk/customers/1234/orders http://foo.ploeh.dk/customers/1234/orders, I'm going to make it http://foo.ploeh.dk/DC884298C70C41798ABE9052DC69CAEE http://foo.ploeh.dk/DC884298C70C41798ABE9052DC69CAEE .... Obviously, that means that my API will have to maintain some sort of two-way lookup table that can map DC884298C70C41798ABE9052DC69CAEE to a request for customer 1234's orders I pity the people who had to work with him, and the many thousands of hours this has probably ended up costing.
- Joker_vD 5y ago
  Oh yeah, having a table with UUIDs instead of customer numbers for primary keys does waste many thousands of hours, that's why CQRS is also a terrible idea.

goto11 5y ago

URLs are not supposed to change since a URL identifies a resource. It is weird arguing for HATEOS as a mitigation for breaking a more fundamental constraint of REST.

Joker_vD 5y ago
> URLs are not supposed to change since a URL identifies a resource Strictly speaking, you're wrong: a URL specifies a location of the resource, and a mechanism for retrieving it. If the location of the resource changes, so would a URL. Even without this philosophical argument, there is an actual practical issue that URLs do change all the time. Both HATEOAS and Persistent URLs are mechanisms to cope with that: HATEOAS proposes to write clients that instead of using hardcoded URLs would use late-bound URLs supplied by the origin server; PURL proposes to hide the origin server behind a proxy that would translate hardcoded URLs used by the clients to the current scheme and either proxy or redirect the requests. The main problem with either solution is that URLs use domain names as their "authority" part, so whenever you lose control of the old domain, the "entry point" URL has to change and there is nothing much you can do about it. Yes, I know that URLs (URNs, actually, IIRC) were supposed to be immutable and eternal, with redirects set up (and maintained somehow, by someone, forever) to point to the current locations, but that didn't work out for obvious reasons.
- goto11 5y ago
  Well if the API moves to a different domain name, HATEOAS will not help you one wit. You still need to hardcode the entry point. I still don't see any reasonable scenario where an API would change the (site-relative) URL's without also changing the semantics of the API. And if the semantics change you would have to rewrite the client anyway. In any case, if you change the URL's without changing the semantics you should respond 301 on the old URL, so even a client with hardcoded URL's would work correctly without the need for HATEOAS.

slver 5y ago

Do you realize that without “constructing a url” you need to go through few roundtrips just to find the resource url you actually need? You force your users through garbage you get support tickets like that. Instead of blaming the users, think why your great approach is actually problematic for them. The single entry point has no benefits unless the api is multi-company, no one specifically hosts it. Is this the case? If no, your hateoas and single url approach is pure cargo cult.