4 ms·

Of all people. What about hypermedia instead of rels? I feel like `ids` param is a hack, clearly the system has a group of objects, should that not be it's ow

Of all people. What about hypermedia instead of rels? I feel like `ids` param is a hack, clearly the system has a group of objects, should that not be it's own collection? For instances: `GET /friends?ids=1,34,54` Could be: `GET /friends/best.json` and `best` to the system in some form, represents 1,34,54. I don't want a RESTful JSON API. I want a REST JSON API.

ryanflorence 13y ago
What if I've selected 5 arbitrary people to unfriend? `PUT /friends/???.json`
- wycats 13y ago
  OP here. Indeed. And importantly, this API makes it possible to restrict the query to a list of documents that the client doesn't already have from another source. In practice, once you start using compound documents with an identity map, there are many cases where existing documents exist on the client and shouldn't be re-fetched. One really simple example is having a number documents that are related to "people" documents. For example, imagine a blog with blog posts and comments, each of which point at an author. When a list of comments for a post is downloaded, each comment will point to an author. Some of those authors will be the same, and some of them will already have been seen from previous posts. This structure allows the client to request only the authors that have not yet been seen (and if you're lucky, it may even be the empty set!).
  - 1qaz2wsx3edc 13y ago
    Yes, the first point is valid, data could be re-fetched. Compounded documents or unions/nested data should only be avoid. I think strong normalization is a good idea. In the second case. The flow could be: GET /posts GET /posts/1/comments GET /posts/1/comments/authors Comments only need to rel to authors, which can be loaded next. Data-binding for the win. I'm not against embedded data as an optimization. It's difficult to fit.
- 1qaz2wsx3edc 13y ago
  Think of it like you're trash bin, you move the files there, one at a time, then empty. State is captured. Then invoked. This is only necessary for transactional requirements. Another method is having a collection sorted and slices. DELETE /teams?id[gt]=10&id[lt]=13 As for non-sequel ids or random ids. It could be possible to support ?id[]=12&id[]=9&id[]=4. Sure it could be /teams/1,2,3 this is just a small detail of the parser. I'm more interesting in how a collection is queried and represented.
  - wycats 13y ago
    Actually, the current Ember Data protocol uses ?id[]=12&id[]=9&id[]=4. There's no good reason for the extra verbosity; it's pretty easy to split over commas and the current format is tricky to parse for platforms that don't already understand it.
rglullis 13y ago
Things bothering me in this proposal: the need for the relation; the use of "posts/1,2,3" to represent a list of resources; the "resource template". None of these are needed with REST/Hypermedia. I've been using djangorestframework, and one of the things that I love about it (instead of tastypie) is the "Browsable API" renderer/parser mode. It's an excellent way to see if your API makes sense: if I'm not able to discover/manipulate resources just by clicking on the links or posting forms, it is a sign that the API design is ill-conceived.
- steveklabnik 13y ago
  I'm sorry, I'm very confused here. Why does hypermedia let you get rid of link relations? How is a 'resource template' different than a <form> hypermedia control in HTML? Why does the URI format matter? It's hypermedia, that's basically irrelevant. It seems you want a "REST"ful API, and that's great. Build that. But then why the first sentence being seemingly upset with some sort of lack of imagined hypermedia support?
steveklabnik 13y ago
> What about hypermedia instead of rels? ... can you elaborate a bit more on what this means? I don't understand what you're trying to say. > I feel like `ids` param is a hack, clearly the system has a group of objects, should that not be it's own collection? I'm not 100% sure what you mean here either, but I'm reading it as "Why not use a comma rather than passing a list of GET parameters?" The answer is "I don't think that's particularly important either." Constructing your own URIs is against the very spirit of REST. Let the server do that for you.
- tomjen3 13y ago
  You shouldn't ever request ids from a server, you should request id -- as a single item -- or a collection defined by the server and named (such as user/friends.json, not users?id=for,bar,baz,foobar). Basically rest apis map exactly one resource to a url and should never use the hack that is ?.
  - steveklabnik 13y ago
    That is simply not true. Can you provide me with some sort of citation on this? Fielding doesn't talk about URL construction in his thesis, and, in fact, specifically mentions things like collections and multiple entities residing in one resource. Also, ? is not a 'hack', I don't know where you're getting that from either.
  - wycats 13y ago
    I used URL Templates (RFC 6570 - http://tools.ietf.org/html/rfc6570 http://tools.ietf.org/html/rfc6570) so that the request to the server is not ad-hoc, but instead fully described by the resource body.
- benatkin 13y ago
  I think 1qaz2wsx3edc means naming the key "hypermedia" instead of "rels". I don't like "rels" because it's hard to pronounce (do I say relationships or rails?) and because it it's an abbreviation. Unfortunately I can't think of something better. When you're competing against nothing, lack of elegance is a difficult problem. The need to be elegant is stronger and you can't simply be as or more elegant than your competition.

ryanflorence 13y ago

What if I've selected 5 arbitrary people to unfriend? `PUT /friends/???.json`

wycats 13y ago
OP here. Indeed. And importantly, this API makes it possible to restrict the query to a list of documents that the client doesn't already have from another source. In practice, once you start using compound documents with an identity map, there are many cases where existing documents exist on the client and shouldn't be re-fetched. One really simple example is having a number documents that are related to "people" documents. For example, imagine a blog with blog posts and comments, each of which point at an author. When a list of comments for a post is downloaded, each comment will point to an author. Some of those authors will be the same, and some of them will already have been seen from previous posts. This structure allows the client to request only the authors that have not yet been seen (and if you're lucky, it may even be the empty set!).
- 1qaz2wsx3edc 13y ago
  Yes, the first point is valid, data could be re-fetched. Compounded documents or unions/nested data should only be avoid. I think strong normalization is a good idea. In the second case. The flow could be: GET /posts GET /posts/1/comments GET /posts/1/comments/authors Comments only need to rel to authors, which can be loaded next. Data-binding for the win. I'm not against embedded data as an optimization. It's difficult to fit.
1qaz2wsx3edc 13y ago
Think of it like you're trash bin, you move the files there, one at a time, then empty. State is captured. Then invoked. This is only necessary for transactional requirements. Another method is having a collection sorted and slices. DELETE /teams?id[gt]=10&id[lt]=13 As for non-sequel ids or random ids. It could be possible to support ?id[]=12&id[]=9&id[]=4. Sure it could be /teams/1,2,3 this is just a small detail of the parser. I'm more interesting in how a collection is queried and represented.
- wycats 13y ago
  Actually, the current Ember Data protocol uses ?id[]=12&id[]=9&id[]=4. There's no good reason for the extra verbosity; it's pretty easy to split over commas and the current format is tricky to parse for platforms that don't already understand it.

rglullis 13y ago

Things bothering me in this proposal: the need for the relation; the use of "posts/1,2,3" to represent a list of resources; the "resource template". None of these are needed with REST/Hypermedia. I've been using djangorestframework, and one of the things that I love about it (instead of tastypie) is the "Browsable API" renderer/parser mode. It's an excellent way to see if your API makes sense: if I'm not able to discover/manipulate resources just by clicking on the links or posting forms, it is a sign that the API design is ill-conceived.

steveklabnik 13y ago
I'm sorry, I'm very confused here. Why does hypermedia let you get rid of link relations? How is a 'resource template' different than a <form> hypermedia control in HTML? Why does the URI format matter? It's hypermedia, that's basically irrelevant. It seems you want a "REST"ful API, and that's great. Build that. But then why the first sentence being seemingly upset with some sort of lack of imagined hypermedia support?

steveklabnik 13y ago

> What about hypermedia instead of rels? ... can you elaborate a bit more on what this means? I don't understand what you're trying to say. > I feel like `ids` param is a hack, clearly the system has a group of objects, should that not be it's own collection? I'm not 100% sure what you mean here either, but I'm reading it as "Why not use a comma rather than passing a list of GET parameters?" The answer is "I don't think that's particularly important either." Constructing your own URIs is against the very spirit of REST. Let the server do that for you.

tomjen3 13y ago
You shouldn't ever request ids from a server, you should request id -- as a single item -- or a collection defined by the server and named (such as user/friends.json, not users?id=for,bar,baz,foobar). Basically rest apis map exactly one resource to a url and should never use the hack that is ?.
- steveklabnik 13y ago
  That is simply not true. Can you provide me with some sort of citation on this? Fielding doesn't talk about URL construction in his thesis, and, in fact, specifically mentions things like collections and multiple entities residing in one resource. Also, ? is not a 'hack', I don't know where you're getting that from either.
- wycats 13y ago
  I used URL Templates (RFC 6570 - http://tools.ietf.org/html/rfc6570 http://tools.ietf.org/html/rfc6570) so that the request to the server is not ad-hoc, but instead fully described by the resource body.
benatkin 13y ago
I think 1qaz2wsx3edc means naming the key "hypermedia" instead of "rels". I don't like "rels" because it's hard to pronounce (do I say relationships or rails?) and because it it's an abbreviation. Unfortunately I can't think of something better. When you're competing against nothing, lack of elegance is a difficult problem. The need to be elegant is stronger and you can't simply be as or more elegant than your competition.