Ask HN: Nested Resources in REST/HTTP API URLs?

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.

Are request parameters not a preferred choice? Especially if filtering for multiple authors.

GET /discussions?author=:authorId1,:authorId2

If both authors had participated.

Or if only one or the other had participated:

GET /discussions?author=:authorId1&author=:authorId2

Be aware that meaningful names such as "thoughts-about-urls" might change (e.g. if you rename the article) in a way that meainingless IDs will not.

If you want your URLs to continue to work then you either need to (a) keep using the previous URL, meaning it's no longer meaningful to the content, (b) change the URL to match the new content, meaning existing links break or (c) support the old and the new versions with a redirection mechanism which is a bunch of effort.

Not saying you shouldn't use meaningful URLs but make sure you're going into the decision with your eyes open and preparing to accept the downsides.

> 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.

Yes! Query string parameters are great for this kind of stuff.

I guess the choice on the URL format depends on how you're going to route that on the server side, so there are multiple ways of doing it.

Depending on the nature of the resource, you might have to be careful with URI canonicalization.

Consider for example the "diff between account balances" endpoint:

GET /account_balance_diff?accid=1&accid=2

Should the diff be presented as from 1 to 2, or from 2 to 1? Query string parameters don't have a particular order to them, and when canonicalizing, some user agent might decide to reorder these parameters.

If you do:

GET /account_balance_diff/1/2

Then, there are two distinct URIs (one for diff 1->2 and other 2->1) and no ambiguity on meaning.

You could also use some kind of index on the parameters to preserve order:

GET /account_balance_diff?acc[1]=123&acc[2]=456

Your other example using a comma should also be fine:

GET /account_balance_diff?accs=1,2

Let's go back to the "discussions" example. What should happen if I GET /discussions without any author id? Our inner guts tell us that there should be something there (after all, I'm filtering _something_), but REST implies absolutely nothing about this relation. To REST and HTTP, you could have a /discussions URL that is completely unrelated to /discussions?filter.

Having a concise, clear URL forming pattern is great. It's not REST though, it's a separate thing, incredibly relevant to us humans, but irrelevant to the architectural style.

A similar confusion happens with error codes. I've seen a lot of people answer 406 Not Acceptable as a status for lock errors and invalid requests. It sounds nice, but it's not designed for that. 406 means the server can't deliver that media type (you asked for PNG but I only have JPG, for example). That 406 is part of the content negotiation mechanism of HTTP, not a lego block to reuse as application logic. The URI is the same, it's role is to be a primary key for the web, not to express hierarchy.

(btw sorry for the long post, I ended up venting a lot and got into several tangents completely unrelated to your comment)