Hacker News Reader

Comment by Jare | Hacker News Reader

I'm not sure about the rest of the stuff, but the idea that you should return links instead of IDs strikes me as horrible. Your REST API should define a way to ID the objects it deals with, and a way to access information about those objects. An example of such information would be an API to return the URL for a photo given its ID (expecting the client to construct that URL is certainly brittle).

My personal best practice would be to build batching facilities for your APIs. Batching is incredibly important when your application data grows.

View on HN

No, no.

The point is that REST uses Hypertext as the Engine of Application State. You might have heard of this as HATEOAS.

Ideally, your API is discoverable given the initial URL. If you return IDs, I have to construct URLs based on information I already have. If you return URLs, I just have to make an HTTP request.

> The idea that you should return links instead of IDs strikes me as horrible.

I've not thought much about this but Roy Fielding disagrees [1].

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

In REST there is no need for IDs at all. There is only URLs; the URL of an object is the only way to refer to it.

URLs, and links. And, more precisely, an URL is the only way to refer to a resource. There may be multiple URLs pointing to the same.

Aside what appared to be a fundamental misunderstanding on the GP's part, there is the legitimate concern that an individual resource shouldn't need to know its own URL. In the article, that was just glossed over, though.

One could, for example, have a book by ID 1 trickle the ID up the application call path, and at a higher level, a complete URL is generated. In fact, the application could simply be a module inside yet another one that wants to add its own ‘namespace’.

What the URL is and how it's generated doesn't matter. All that does is that the URL is made available (discoverable), and that it goes to the right resource, however that happens.

I almost completely agree, but a problem I often encounter in REST API design is: how to do searches?

Let's say we have an "Event" Resource and it belongs to a "Location" Resource and the Event belongs to "Category" Resources. If you want to provide an endpoint to search events with a GET requests and filter based on Location and Categories (which are identified by URLs) you can end up with really long query strings.

/events?location=URL1&categories[]=URL2&categories[]=URL3&categories[]=URL4&...

This is not only ugly, it can bring up problems on both clients and servers.

Any suggestions on how to handle this?

Why use GET instead of POST? Just POST a document with the parameters to filter, and the server creates a new resource with the search results and returns its URL to the client, which can then GET it.

There's really no need to create a separate URL; it's reasonable for POST requests to contain response bodies.

I don't think there's anything particularly unRESTful about using non-URL ids in that case. The critical thing is that the client isn't using out-of-band knowledge (i.e. what the developer read in the API documentation and hardcoded into the client) to construct the query.

I'm not sure quite where you're going. You agree that having a client construct its own URLs from IDs is brittle. But then you propose an API to turn photo IDs into URLs—but that service itself lives at a particular URL, and is equally subject to change!

Can you explain a bit more? I'm just surprised because returning URLs (not IDs) is a fundamental idea of proper REST.

If the API entry point is subject to change then the very ability to access the service is in trouble, isn't it?

In particular, my doubts about IDs vs URLs is the ability to store those pieces of data in the client (or intermediate caches) - if the service URLs or namespaces change, the client-side URLs become useless even after the client updates the service entry point. With IDs, that information would still be usable.

I'm absolutely no expert on this so I'm probably in the "HTTP API, not REST API" side of the problem.

Good point. I think the best way to handle URL changes is to use HTTP status 301 (permanently moved) for the old URLs. This can be applied consistently to APIs and webpages. This allows discoverable resources as well as re-discoverable URLs.

This is how a good API would handle the change. Deprecate the first URL, do a redirect to the new one for a period of time, then remove the original endpoints.

Same concept as deprecating code. You don't wipe it out straight away because you have no idea what else might rely on it or how fast they are to react (within reason).

As for the arguments about not using HTTP request methods - they're standard, and are implemented uniformly everywhere (for the best part). Your API isn't standard, but if all APIs use HTTP and its request methods correctly, you only need to learn the general HTTP spec to generally understand all APIs.

Resources and URL structure afterwards is a matter of opinion. What may seem RESTful to me might not be to someone else.

Migrating anything will always be hard, sometimes services even migrate IDs (to something that is easier to shard intelligently against). As others mentioned you could either put redirects everywhere, but most services just version their REST APIs and then write glue to tie old interfaces to newer data models, see for example Twitter, Amazon AWS, and Instagram.

One other semantic nitpick is that a URL is a subset of URI, which stands for Universal Resource Identifier, so in some sense you could make a philosophical argument that URI and IDs are/should be the same thing. If you were really crazy you could store URLs in your DB (obviously not a good idea for many other reasons).

> In particular, my doubts about IDs vs URLs is the ability to store those pieces of data in the client (or intermediate caches) - if the service URLs or namespaces change, the client-side URLs become useless even after the client updates the service entry point.

Which is OK, because the client can re-traverse the service to get back to those resources which are now invalid.

Reply on news.ycombinator.com