URI generation from ids should be stateless and uniform for discoverability

[reinh]

Currently, in order for a client to generate a URI based on the "ID Style" specification, the client would need to discover and statefully maintain the out-of-band knowledge required to generate the URIs specific to that API. To quote the current specification language, emphasis mine:

"A base URL that represents the type of the related resource (this must be hardcoded in the client).

In the example given for "To-one relationships", the mapping between "author" and "people" is out-of-band knowledge that significantly reduces the discoverability and programmability of an API in the "ID Style" (and seems at odds with the intentions of the RESTful design and hypermedia in particular).

(As an aside, I would suggest that the "ID Style" of API is at best only a pseudo-hypermedia format and is mainly useful as a transitional step between plain JSON and "real" hypermedia formats. Perhaps the specification could call this out to better manage expectations. I suspect that a minimum viable hypermedia format involves at least URI templates.)

In order to allow "dumb" clients to programmatically access the API by traversing hypermedia links between resources, the heuristic used to generate URIs from ids should be uniform (the same across all compliant implementations of the spec) and stateless or minimally stateful (requiring a minimum amount of out-of-band information to generate the URIs). And example of such a heuristic follows, with the significant change highlighted:

---

To-many Relationships

• A base URL that represents the type of the related resource. This is defined as the plural form of the related resource; in this case, authors.
• ?ids=
• A comma-separated list of the specified IDs

---

If the location of the resource is actually at the "people" endpoint then this knowledge can be transfered to the client in-band via a permanent redirect.

[steveklabnik]

Right. The "ID style" is more transitional, it isn't ideal. We'd like to support a transitional path from "Rails REST" to a better way. As you mention yourself. I think that 'calling it out' would be useful.

[lukfugl]

👍 to @steveklabnik. I look at URL-style as the fully HTTP, REST approach, with discoverability, etc. and ID-style as transitional for backwards compatibility with those server and client frameworks that currently focus inordinately on IDs.

[lukfugl]

i.e. ID-style intentionally the full benefits of HTTP and REST design for compatibility

[reinh]

@lukfugl Yep. Since the URI-templates format can be bolted onto the "ID Style", I think we could suggest transitioning first to "ID-Style" from "Rails 'REST' Style" and then to URI-templates as this would maintain the most backwards compatibility while introducing the most hypermedia benefits.

[steveklabnik]

And documenting this process will be useful to help drive adoption.

[paddycarver]

A little bit of an aside here, but I see people favouring ?ids=1,2,3. Is there a reason this format is favoured over ?id=1&id=2&id=3? I know at least some languages allow returning multiple values for each key, but I don't remember if all of them do. I couldn't find anything about it in the RFC.

[reinh]

@paddyforan It's an unnecessarily verbose format with limited support. What's the upside?

[paddycarver]

@reinh I wasn't sure if support was limited or not, to be honest. Which is why I asked. It seems like a more semantic way to accomplish things to me, so I thought it may be part of a spec, but I couldn't find any reference to it. I'm all for going with the more supported option, I just am surprised that comma-delimited lists are the more supported option.

[reinh]

@paddyforan Unfortunately, it's not very simple. The spec is completely silent on the issue so there is no defined behavior. Some servers will return an array while others will return the first or last value. Even for servers that return an array, the ordering is not always guaranteed. There's even an exploit based on this behavior called HPP that this OWASP talk digs into.

At least with foos=1,2,3 we have a chance to define the behavior explicitly for all compliant servers without running headlong into incompatible legacy behaviors or security concerns.

[paddycarver]

That all seems pretty reasonable to me. I wish servers had standardised around returning an array (it feels more semantic/proper for some reason, I really can't explain why), but it seems like rolling our own in this case may actually be the right thing to do.

Thanks for the explanation!

[steveklabnik]

I think this discussion has come to a close. I'll be doing more to signal the difference between the two styles soon.