3 ms·

It doesn’t actually matter unless your API is expected to be consumed without any particular entry point. If you can expect users to enter at specific points, y

It doesn’t actually matter unless your API is expected to be consumed without any particular entry point. If you can expect users to enter at specific points, you can represent state as hypertext and give them links (URLs) rather than ids. They don’t need to know or care about your URL patterns, they just need to follow the hyperlinks you provide. You can do the same even if some entry points are known, and then I'd follow the approach of /top-level/:id, because it’s at least a predictable way to start. If further API access requires discovery, go wild and format your URLs how it works best for your service. Just keep them unique and stable, because stable URLs are cool!

tasuki 4y ago
> They don’t need to know or care about your URL patterns, they just need to follow the hyperlinks you provide. This is REST. As a backend dev I've attempted this several times, and the consumers of my API never cared about the hyperlinks. I've tried explaining that the 'delete' hyperlink is only going to be present when the user is authorized to delete the resource, and isn't that wonderful and making your life easier? It turns out, (my) API consumers want to hardcode URLs on their side and have the payload include a can-delete flag. Same across several companies. I've since mostly given up on making interfaces restful. Anyone has experience with this going the same or differently?
- eterps 4y ago
  Yeah everyone is fine with hardcoding API URLs, even submitting the resulting client to an app store. You're not going to fix that unless you (initially) make the URLs unpredictable (that is, make the links the only way to know a URL). But that will (initially) be costly to do. And is probably annoying to your API consumers as well. So only consider this if you need reduced coupling and there is clear value in avoiding hardcoded URLs.
- eyelidlessness 4y ago
  > As a backend dev I've attempted this several times, and the consumers of my API never cared about the hyperlinks. […] Anyone has experience with this going the same or differently? I’ve seen it work exceedingly well with a browsable interface, like the one provided by Django REST Framework (not an endorsement of the framework per se; it does a lot of stuff very nicely, but other stuff can be a pain). If the API is human-discoverable, that makes the appeal of hyperlinks (actually linked in the browsable interface) a lot more obvious. > I've tried explaining that the 'delete' hyperlink is only going to be present when the user is authorized to delete the resource, and isn't that wonderful and making your life easier? It turns out, (my) API consumers want to hardcode URLs on their side and have the payload include a can-delete flag. Same across several companies. Not to nitpick the RESTfulness of this design, but I think it’s interesting that a more purist HATEOAS approach would be closer to what they wanted. Example response: HTTP/1.1 200 OK Allow: DELETE, GET, PATCH, PUT Content-Type: application/json … { "url": "https://example.com/foos/any-key", … } Note `Allow`, that’s a standard HTTP header many clients can parse and understand automatically, and might even give them their can-delete flag for free. They can hard code the URL if they like, but they already have the URL because it’s the same one, for the same resource they already requested. Or, if they requested a listing… sure, again, they can hard-code the listed resources but I think the convenience of including URLs is a probably a lot more obviously appealing there. Coming back to DRF’s browsable interface, it similarly uses standard HTTP semantics, in this case content negotiation. If it receives a request with `Accept: text/html` it responds with a web representation of whichever resource you requested. If the request is authorized to perform other actions on that resource—determined by the same `Allow` header—the web representation also includes a form to perform those actions. This isn’t to say everyone will see the appeal! But in my experience it’s a lot easier to grasp when an API really does embrace HATEOAS.
- clusterhacks 4y ago
  >consumers of my API never cared about the hyperlinks. Exact same experience. Advocating for HATEOS actually confused developers in my org. In the end, I had precisely zero consumers not hardcode URLs client-side. I was pushing on my team for us to adopt more generic client-side code so that we could iterate on web UIs quicker but just couldn't get buy-in. I had a basic collection+json web client that I demo'd for browsing various services that returned that hypermedia type but people just weren't interested. It was (and still is) the case that most of our internal apps fit the "simple collection" data and manipulation model. I probably blew it by not doing any nice css styling of the demo web client. I stay from the web app space internally now. If I'm being honest, my org's web projects mostly fail these days. The common pattern goes something like legacy desktop app -> web app generates excitement (modern UI! node.js! CSS improvements!), dev starts, dev continues for indeterminate time, users lose interest and buy external tools, team inherits other legacy desktop apps, dev team adopts new legacy app to repeat on. I'm embarrassed about my teams' results in this general space.

tasuki 4y ago

> They don’t need to know or care about your URL patterns, they just need to follow the hyperlinks you provide. This is REST. As a backend dev I've attempted this several times, and the consumers of my API never cared about the hyperlinks. I've tried explaining that the 'delete' hyperlink is only going to be present when the user is authorized to delete the resource, and isn't that wonderful and making your life easier? It turns out, (my) API consumers want to hardcode URLs on their side and have the payload include a can-delete flag. Same across several companies. I've since mostly given up on making interfaces restful. Anyone has experience with this going the same or differently?

eterps 4y ago
Yeah everyone is fine with hardcoding API URLs, even submitting the resulting client to an app store. You're not going to fix that unless you (initially) make the URLs unpredictable (that is, make the links the only way to know a URL). But that will (initially) be costly to do. And is probably annoying to your API consumers as well. So only consider this if you need reduced coupling and there is clear value in avoiding hardcoded URLs.
eyelidlessness 4y ago
> As a backend dev I've attempted this several times, and the consumers of my API never cared about the hyperlinks. […] Anyone has experience with this going the same or differently? I’ve seen it work exceedingly well with a browsable interface, like the one provided by Django REST Framework (not an endorsement of the framework per se; it does a lot of stuff very nicely, but other stuff can be a pain). If the API is human-discoverable, that makes the appeal of hyperlinks (actually linked in the browsable interface) a lot more obvious. > I've tried explaining that the 'delete' hyperlink is only going to be present when the user is authorized to delete the resource, and isn't that wonderful and making your life easier? It turns out, (my) API consumers want to hardcode URLs on their side and have the payload include a can-delete flag. Same across several companies. Not to nitpick the RESTfulness of this design, but I think it’s interesting that a more purist HATEOAS approach would be closer to what they wanted. Example response: HTTP/1.1 200 OK Allow: DELETE, GET, PATCH, PUT Content-Type: application/json … { "url": "https://example.com/foos/any-key", … } Note `Allow`, that’s a standard HTTP header many clients can parse and understand automatically, and might even give them their can-delete flag for free. They can hard code the URL if they like, but they already have the URL because it’s the same one, for the same resource they already requested. Or, if they requested a listing… sure, again, they can hard-code the listed resources but I think the convenience of including URLs is a probably a lot more obviously appealing there. Coming back to DRF’s browsable interface, it similarly uses standard HTTP semantics, in this case content negotiation. If it receives a request with `Accept: text/html` it responds with a web representation of whichever resource you requested. If the request is authorized to perform other actions on that resource—determined by the same `Allow` header—the web representation also includes a form to perform those actions. This isn’t to say everyone will see the appeal! But in my experience it’s a lot easier to grasp when an API really does embrace HATEOAS.
clusterhacks 4y ago
>consumers of my API never cared about the hyperlinks. Exact same experience. Advocating for HATEOS actually confused developers in my org. In the end, I had precisely zero consumers not hardcode URLs client-side. I was pushing on my team for us to adopt more generic client-side code so that we could iterate on web UIs quicker but just couldn't get buy-in. I had a basic collection+json web client that I demo'd for browsing various services that returned that hypermedia type but people just weren't interested. It was (and still is) the case that most of our internal apps fit the "simple collection" data and manipulation model. I probably blew it by not doing any nice css styling of the demo web client. I stay from the web app space internally now. If I'm being honest, my org's web projects mostly fail these days. The common pattern goes something like legacy desktop app -> web app generates excitement (modern UI! node.js! CSS improvements!), dev starts, dev continues for indeterminate time, users lose interest and buy external tools, team inherits other legacy desktop apps, dev team adopts new legacy app to repeat on. I'm embarrassed about my teams' results in this general space.