Just starting out on my first RESTful API project, which I will be
hosting on Google App Engine and using Objectify as the ORM. This led
me to wonder if the resource /dogs should return the dog objects or
keys to the dog objects. Would the general answer be that /dogs
should return the dog objects and that something like /dogs?fields=id
could return just the key field?
Just wondering...
Thanks!
RB
PS - Many thanks to the apigee folks for their great videos and tools
(e.g. the testing console) - way cool.
Richard,
welcome and you will definitely be getting some great responses.
Here's my basic understanding. /dogs is a collection of resources and
should return a list of such and items that are actual resources
should have their own URI, such as /dogs/dogid. Parameters are more
for adjusting the data returned by a resource, so in the dogs case, if
you wanted to limit how many records came back you would do so like /
dogs/?limit=50.
The idea is a anything that is a resource should have it's own URI
location.
The value in separating it, is that - Your details can have different cache timeouts, and changing one does not invalidate your entire client cache - The different list will only change when a new dog is added/removed so that can have a different lifespan than detail changes (same expiration thing)
I have also seen APIs that include some details in the list (e.g., ID) because that helps pick the entries out that you want or provide "summary" information. The list document is less cacheable if you do that, but that might be an appropriate trade off to simplify summary pages.
On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit <jurki...@gmail.com> wrote: > Richard, > welcome and you will definitely be getting some great responses.
> Here's my basic understanding. /dogs is a collection of resources and > should return a list of such and items that are actual resources > should have their own URI, such as /dogs/dogid. Parameters are more > for adjusting the data returned by a resource, so in the dogs case, if > you wanted to limit how many records came back you would do so like / > dogs/?limit=50.
> The idea is a anything that is a resource should have it's own URI > location.
Thanks Richard, I hadn't thought about how the "just return links"
approach helps with caching.
For what I'm working on so far, I ended up going with returning the
entire resource because of situations like this:
/stores/1/transactions
A "use case" for our API would definitely be to list all the
transactions for a given store. If I just include the links, I'd have
one HTTP call to our API for each transaction! That wouldn't scale
well. Of course, that end point will also have defaults for "limit"
and "offset" query params. Also, our current POX API supports a
"transactions_list" call so I'd need a way to get a bundle of
resources back. I can see from a purely "navigating the api"
standpoint, that's way more data than is needed... but we're also
implementing the "fields" option so users can decide they just want a
subset of the resource returned to them.
So it could be /dogs?fields=name,id (assuming each dog resource also
has hypermedia links including "self" to get the full resource)
Just another approach to take.
I'm not sure it really matters, but we're also going to go with
"_links" using the HAL+json format for just the links part. Other than
that, it will be in a "dogs" parent node or <dogs><dog></dog><dog></
dog>...</dogs> in XML. The custom content type we'll use is the same
for a resource but with an extra "s" on the end to indicate a
collection. For partial responses, we append "_partial". Not sure if
that's standard or not, but it at least tells the client via media
type that it's not a full resource so some fields may not be there.
On Feb 23, 11:13 am, Daniel Roop <dan...@danielroop.com> wrote:
> The value in separating it, is that
> - Your details can have different cache timeouts, and changing one does not
> invalidate your entire client cache
> - The different list will only change when a new dog is added/removed so
> that can have a different lifespan than detail changes (same expiration
> thing)
> I have also seen APIs that include some details in the list (e.g., ID)
> because that helps pick the entries out that you want or provide "summary"
> information. The list document is less cacheable if you do that, but that
> might be an appropriate trade off to simplify summary pages.
> On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit <jurki...@gmail.com> wrote:
> > Richard,
> > welcome and you will definitely be getting some great responses.
> > Here's my basic understanding. /dogs is a collection of resources and
> > should return a list of such and items that are actual resources
> > should have their own URI, such as /dogs/dogid. Parameters are more
> > for adjusting the data returned by a resource, so in the dogs case, if
> > you wanted to limit how many records came back you would do so like /
> > dogs/?limit=50.
> > The idea is a anything that is a resource should have it's own URI
> > location.
Thank you to all for your responses! All are relevant to my situation
- returning a list of Commitments that different clients will probably
want to handle differently. Some clients, perhaps on a phone, would
only want to show a list of "links" (a la Daniel's first response).
Other clients, perhaps on a device with a bigger screen, would want to
show additional identification info (name, description), along with
the link. Thus Luke's suggestion of "So it could be /dogs?
fields=name,id (assuming each dog resource also has hypermedia links
including "self" to get the full resource)" seems like the way to go.
Different clients can choose different field lists and the default (/
dogs) would provide the all the fields for all the dogs/commitments -
for those clients that would want that (a la Jacques).
Thanks again!
RB
@Luke - The caching insight (a benefit of "just the links") was
Daniel's contribution, not mine :)
On Feb 23, 10:07 am, Luke Stokes <luke.sto...@gmail.com> wrote:
> Thanks Richard, I hadn't thought about how the "just return links"
> approach helps with caching.
> For what I'm working on so far, I ended up going with returning the
> entire resource because of situations like this:
> /stores/1/transactions
> A "use case" for our API would definitely be to list all the
> transactions for a given store. If I just include the links, I'd have
> one HTTP call to our API for each transaction! That wouldn't scale
> well. Of course, that end point will also have defaults for "limit"
> and "offset" query params. Also, our current POX API supports a
> "transactions_list" call so I'd need a way to get a bundle of
> resources back. I can see from a purely "navigating the api"
> standpoint, that's way more data than is needed... but we're also
> implementing the "fields" option so users can decide they just want a
> subset of the resource returned to them.
> So it could be /dogs?fields=name,id (assuming each dog resource also
> has hypermedia links including "self" to get the full resource)
> Just another approach to take.
> I'm not sure it really matters, but we're also going to go with
> "_links" using the HAL+json format for just the links part. Other than
> that, it will be in a "dogs" parent node or <dogs><dog></dog><dog></
> dog>...</dogs> in XML. The custom content type we'll use is the same
> for a resource but with an extra "s" on the end to indicate a
> collection. For partial responses, we append "_partial". Not sure if
> that's standard or not, but it at least tells the client via media
> type that it's not a full resource so some fields may not be there.
> On Feb 23, 11:13 am, Daniel Roop <dan...@danielroop.com> wrote:
> > Richard,
> > I tend to keep my list to links (or ids but preferabbly links) and then as
> > Jacques suggested have a seperate URL for the details.
> > The value in separating it, is that
> > - Your details can have different cache timeouts, and changing one does not
> > invalidate your entire client cache
> > - The different list will only change when a new dog is added/removed so
> > that can have a different lifespan than detail changes (same expiration
> > thing)
> > I have also seen APIs that include some details in the list (e.g., ID)
> > because that helps pick the entries out that you want or provide "summary"
> > information. The list document is less cacheable if you do that, but that
> > might be an appropriate trade off to simplify summary pages.
> > On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit <jurki...@gmail.com> wrote:
> > > Richard,
> > > welcome and you will definitely be getting some great responses.
> > > Here's my basic understanding. /dogs is a collection of resources and
> > > should return a list of such and items that are actual resources
> > > should have their own URI, such as /dogs/dogid. Parameters are more
> > > for adjusting the data returned by a resource, so in the dogs case, if
> > > you wanted to limit how many records came back you would do so like /
> > > dogs/?limit=50.
> > > The idea is a anything that is a resource should have it's own URI
> > > location.
I like the idea of making the API flexible and letting the client be a
little creative, as long as that won't impact your caching strategy
(example, if each client decides they want a slightly different
resource representation). Still though, the "fields" approach seems
like a nice solution for a few things.
On Feb 24, 3:16 pm, Richard Berger <richardlan...@gmail.com> wrote:
> Thank you to all for your responses! All are relevant to my situation
> - returning a list of Commitments that different clients will probably
> want to handle differently. Some clients, perhaps on a phone, would
> only want to show a list of "links" (a la Daniel's first response).
> Other clients, perhaps on a device with a bigger screen, would want to
> show additional identification info (name, description), along with
> the link. Thus Luke's suggestion of "So it could be /dogs?
> fields=name,id (assuming each dog resource also has hypermedia links
> including "self" to get the full resource)" seems like the way to go.
> Different clients can choose different field lists and the default (/
> dogs) would provide the all the fields for all the dogs/commitments -
> for those clients that would want that (a la Jacques).
> Thanks again!
> RB
> @Luke - The caching insight (a benefit of "just the links") was
> Daniel's contribution, not mine :)
> On Feb 23, 10:07 am, Luke Stokes <luke.sto...@gmail.com> wrote:
> > Thanks Richard, I hadn't thought about how the "just return links"
> > approach helps with caching.
> > For what I'm working on so far, I ended up going with returning the
> > entire resource because of situations like this:
> > /stores/1/transactions
> > A "use case" for our API would definitely be to list all the
> > transactions for a given store. If I just include the links, I'd have
> > one HTTP call to our API for each transaction! That wouldn't scale
> > well. Of course, that end point will also have defaults for "limit"
> > and "offset" query params. Also, our current POX API supports a
> > "transactions_list" call so I'd need a way to get a bundle of
> > resources back. I can see from a purely "navigating the api"
> > standpoint, that's way more data than is needed... but we're also
> > implementing the "fields" option so users can decide they just want a
> > subset of the resource returned to them.
> > So it could be /dogs?fields=name,id (assuming each dog resource also
> > has hypermedia links including "self" to get the full resource)
> > Just another approach to take.
> > I'm not sure it really matters, but we're also going to go with
> > "_links" using the HAL+json format for just the links part. Other than
> > that, it will be in a "dogs" parent node or <dogs><dog></dog><dog></
> > dog>...</dogs> in XML. The custom content type we'll use is the same
> > for a resource but with an extra "s" on the end to indicate a
> > collection. For partial responses, we append "_partial". Not sure if
> > that's standard or not, but it at least tells the client via media
> > type that it's not a full resource so some fields may not be there.
> > On Feb 23, 11:13 am, Daniel Roop <dan...@danielroop.com> wrote:
> > > Richard,
> > > I tend to keep my list to links (or ids but preferabbly links) and then as
> > > Jacques suggested have a seperate URL for the details.
> > > The value in separating it, is that
> > > - Your details can have different cache timeouts, and changing one does not
> > > invalidate your entire client cache
> > > - The different list will only change when a new dog is added/removed so
> > > that can have a different lifespan than detail changes (same expiration
> > > thing)
> > > I have also seen APIs that include some details in the list (e.g., ID)
> > > because that helps pick the entries out that you want or provide "summary"
> > > information. The list document is less cacheable if you do that, but that
> > > might be an appropriate trade off to simplify summary pages.
> > > On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit <jurki...@gmail.com> wrote:
> > > > Richard,
> > > > welcome and you will definitely be getting some great responses.
> > > > Here's my basic understanding. /dogs is a collection of resources and
> > > > should return a list of such and items that are actual resources
> > > > should have their own URI, such as /dogs/dogid. Parameters are more
> > > > for adjusting the data returned by a resource, so in the dogs case, if
> > > > you wanted to limit how many records came back you would do so like /
> > > > dogs/?limit=50.
> > > > The idea is a anything that is a resource should have it's own URI
> > > > location.
Just following up on this - do you have a pointer to some code/
examples that would generate the:
{
"links" : {
"href" : "http://api.example.com/dogs/1"
}
}
I am using Restlet and started investigating RDF to generate links/
hrefs just like the ones you suggested - but I am not sure if I am
going in the right direction. (I am thinking that there is some
framework help here, rather than my constructing and populating those
fields by hand (which I think I can do)).
Thanks!
RB
On Feb 23, 9:13 am, Daniel Roop <dan...@danielroop.com> wrote:
> The value in separating it, is that
> - Your details can have different cache timeouts, and changing one does not
> invalidate your entire client cache
> - The different list will only change when a new dog is added/removed so
> that can have a different lifespan than detail changes (same expiration
> thing)
> I have also seen APIs that include some details in the list (e.g., ID)
> because that helps pick the entries out that you want or provide "summary"
> information. The list document is less cacheable if you do that, but that
> might be an appropriate trade off to simplify summary pages.
> Hope that helps.On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit <jurki...@gmail.com> wrote:
> > Richard,
> > welcome and you will definitely be getting some great responses.
> > Here's my basic understanding. /dogs is a collection of resources and
> > should return a list of such and items that are actual resources
> > should have their own URI, such as /dogs/dogid. Parameters are more
> > for adjusting the data returned by a resource, so in the dogs case, if
> > you wanted to limit how many records came back you would do so like /
> > dogs/?limit=50.
> > The idea is a anything that is a resource should have it's own URI
> > location.
I haven't seen a standard library to do this yet. I know hal+json defines a structure almost identical, and wrml defines one like I have suggested. But I have yet to see anything pop up in the wild that renders it.
At my office we have some libraries, but I haven't been able to convince anyone to open source them yet.
On Sun, Mar 4, 2012 at 8:36 PM, Richard Berger <richardlan...@gmail.com>wrote:
> Just following up on this - do you have a pointer to some code/ > examples that would generate the: > { > "links" : { > "href" : "http://api.example.com/dogs/1" > } > }
> I am using Restlet and started investigating RDF to generate links/ > hrefs just like the ones you suggested - but I am not sure if I am > going in the right direction. (I am thinking that there is some > framework help here, rather than my constructing and populating those > fields by hand (which I think I can do)).
> Thanks! > RB
> On Feb 23, 9:13 am, Daniel Roop <dan...@danielroop.com> wrote: > > Richard,
> > I tend to keep my list to links (or ids but preferabbly links) and then > as > > Jacques suggested have a seperate URL for the details.
> > The value in separating it, is that > > - Your details can have different cache timeouts, and changing one does > not > > invalidate your entire client cache > > - The different list will only change when a new dog is added/removed so > > that can have a different lifespan than detail changes (same expiration > > thing)
> > I have also seen APIs that include some details in the list (e.g., ID) > > because that helps pick the entries out that you want or provide > "summary" > > information. The list document is less cacheable if you do that, but that > > might be an appropriate trade off to simplify summary pages.
> > Hope that helps.On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit < > jurki...@gmail.com> wrote: > > > Richard, > > > welcome and you will definitely be getting some great responses.
> > > Here's my basic understanding. /dogs is a collection of resources and > > > should return a list of such and items that are actual resources > > > should have their own URI, such as /dogs/dogid. Parameters are more > > > for adjusting the data returned by a resource, so in the dogs case, if > > > you wanted to limit how many records came back you would do so like / > > > dogs/?limit=50.
> > > The idea is a anything that is a resource should have it's own URI > > > location.
IMO I think the /dogs should not return the objects but a list of uri. I like Daniel's "entries" approach as it is close to the atom protocole<http://en.wikipedia.org/wiki/Atom_(standard)>.
Let's say you return the object. Then you are probably going to you use a simple JSON encoding mechanism to take care of the encoding for you. Then what happens if you have nested objects under your dogs ? Let's say a dog has an owner and then an owner has relationships with other human beings etc. Returning dogs could mean to return all your data graph... You do not want to do that.
Depending on your use case, you should evaluate the pros and cons to adding information like "tittle"/"summary" etc to the uri list to avoid making too many queries after listing the dogs.
But if you have to loop on all the dogs/ after your first request, I think you should ask yourself if your doing the right thing... Maybe you should change your application logic to have a more specific query.
On Thursday, February 23, 2012 7:07:51 PM UTC+1, Luke Stokes wrote:
> Thanks Richard, I hadn't thought about how the "just return links" > approach helps with caching.
> For what I'm working on so far, I ended up going with returning the > entire resource because of situations like this:
> /stores/1/transactions
> A "use case" for our API would definitely be to list all the > transactions for a given store. If I just include the links, I'd have > one HTTP call to our API for each transaction! That wouldn't scale > well. Of course, that end point will also have defaults for "limit" > and "offset" query params. Also, our current POX API supports a > "transactions_list" call so I'd need a way to get a bundle of > resources back. I can see from a purely "navigating the api" > standpoint, that's way more data than is needed... but we're also > implementing the "fields" option so users can decide they just want a > subset of the resource returned to them.
> So it could be /dogs?fields=name,id (assuming each dog resource also > has hypermedia links including "self" to get the full resource)
> Just another approach to take.
> I'm not sure it really matters, but we're also going to go with > "_links" using the HAL+json format for just the links part. Other than > that, it will be in a "dogs" parent node or <dogs><dog></dog><dog></ > dog>...</dogs> in XML. The custom content type we'll use is the same > for a resource but with an extra "s" on the end to indicate a > collection. For partial responses, we append "_partial". Not sure if > that's standard or not, but it at least tells the client via media > type that it's not a full resource so some fields may not be there.
> On Feb 23, 11:13 am, Daniel Roop <dan...@danielroop.com> wrote: > > Richard,
> > I tend to keep my list to links (or ids but preferabbly links) and then > as > > Jacques suggested have a seperate URL for the details.
> > The value in separating it, is that > > - Your details can have different cache timeouts, and changing one does > not > > invalidate your entire client cache > > - The different list will only change when a new dog is added/removed so > > that can have a different lifespan than detail changes (same expiration > > thing)
> > I have also seen APIs that include some details in the list (e.g., ID) > > because that helps pick the entries out that you want or provide > "summary" > > information. The list document is less cacheable if you do that, but > that > > might be an appropriate trade off to simplify summary pages.
> > On Thu, Feb 23, 2012 at 10:35 AM, Jacques_thekit <jurki...@gmail.com> > wrote: > > > Richard, > > > welcome and you will definitely be getting some great responses.
> > > Here's my basic understanding. /dogs is a collection of resources and > > > should return a list of such and items that are actual resources > > > should have their own URI, such as /dogs/dogid. Parameters are more > > > for adjusting the data returned by a resource, so in the dogs case, if > > > you wanted to limit how many records came back you would do so like / > > > dogs/?limit=50.
> > > The idea is a anything that is a resource should have it's own URI > > > location.
