What are your thoughts on intentionally "breaking the rules" on a collection

[Jason Mulligan]

I have a biz requirement that dictates a truly RESTful API will not always work, e.g. a collection that has 10k - 500k reps. So I proposed to my coworkers that we leverage the query string & "composite=true" to return an Array of Objects instead of an Array of URIs (relative or absolute, doesn't matter). This allows our API to default to RMM3, and when needed, we can enable a "2.5" result on collections only. The implicit value be "false".

The Objects in the Array would be the result of the URIs; there's no deep dive / recursion possible; it is simply a method to reduce requests under certain constraints.

[Dietrich Schulten]

What is it the clients really need? Huge numbers of reps? Or a small selection?
Anyway, I am not aware of any rule that forbids to embed the actual object rather than linking to it.
Kind regards
Dietrich

Am 15.11.2012 18:45 schrieb "Jason Mulligan" <atta...@gmail.com>:

I have a biz requirement that dictates a truly RESTful API will not always work, e.g. a collection that has 10k - 500k reps. So I proposed to my coworkers that we leverage the query string & "composite=true" to return an Array of Objects instead of an Array of URIs (relative or absolute, doesn't matter). This allows our API to default to RMM3, and when needed, we can enable a "2.5" result on collections only. The implicit value be "false".

The Objects in the Array would be the result of the URIs; there's no deep dive / recursion possible; it is simply a method to reduce requests under certain constraints.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Jason Mulligan]

Well, granular permissions cannot be expressed adequately if you put Objects in the response of a collection; it's not very HATEOAS-y, because the collection is an entity, and everything under it is a separate entity with relationships.

It's a "big data" api scenario; and one potential Client is IE8 which has a real world ceiling of around 300 requests in serial.

[Steve Klabnik]

Entities != resources != representations.

There's nothing inherently un-RESTful about returning a big collection. 

[Jason Mulligan]

Jesus, this is why google groups fails. You're hung up on semantics which map accurately.

en·ti·ty/ˈentitē/

Noun:

A thing with distinct and independent existence. Existence; being: "entity and nonentity".

re·source/ˈrēˌsôrs/

Noun:

A stock or supply of money, materials, staff, and other assets that can be drawn on by a person or organization in order to function...

rep·re·sen·ta·tion/ˌrepriˌzenˈtāSHən/

Noun:

The action of speaking or acting on behalf of someone or the state of being so represented. The description or portrayal of someone or something in a particular way or as being of a certain nature.

[Mike Schinkel]

Hi Jason,

Just fyi, the term "resource" and "representation" have different formal meanings in Web Architecture:

http://www.w3.org/TR/webarch/#id-resources

http://www.w3.org/TR/webarch/#internet-media-type

I am not aware of "entity" having a formal definition in Web Architecture but I could be wrong there.

-Mike

[Steve Klabnik]

Sec 5.2.1.1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

[Jason Mulligan]

I've read that, what are you suggesting I review?

-- 

Jason Mulligan

Sent with Sparrow

On Thursday, 15 November, 2012 at 3:26 PM, Steve Klabnik wrote:

Sec 5.2.1.1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

[Steve Klabnik]

Well, half of that was directed at Mike. The second half was directed
at you, pointing at dictionary definitions of these three words rather
than the REST ones.

When I read

> I have a biz requirement that dictates a truly RESTful API will not always work, e.g. a collection that has 10k - 500k reps.

I am not sure what you mean. A 'collection that has 10k
representations' doesn't make sense. Your next sentence

> to return an Array of Objects instead of an Array of URIs (relative or absolute, doesn't matter). This allows our API to default to RMM3, and when needed, we can enable a "2.5" result on collections only.

Seems to imply that you think that there is a 1-1-1 correlation
between entities, resources, and representations.

What you're asking about doing is having a resource, which gives a
representation, that is a mapping from 10k-500k entities. That is
perfectly fine. There is nothing 'un-RESTful' about it.

[Mike Kelly]

you can embed however many resources into one representation as you want. It's unlikely to cache very well, but it's a perfectly valid approach that's doesn't violate any REST constraints.

[Steve Klabnik]

Exactly.