Objects vs. Keys
147 views
Skip to first unread message
Richard Berger
Feb 23, 2012, 1:46:43 AM2/23/12
to API Craft
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.
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.
Jacques_thekit
Feb 23, 2012, 10:35:11 AM2/23/12
to API Craft
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.
- J
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.
- J
Daniel Roop
Feb 23, 2012, 12:13:46 PM2/23/12
to api-...@googlegroups.com
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.
GET /dogs
"entries" : [
{
"links" : {
"href" : "http://api.example.com/dogs/1"
}
},
{
"links" : {
"href" : "http://api.example.com/dogs/2"
}
},
{
"links" : {
"href" : "http://api.example.com/dogs/3"
}
}
]
Then the details would look like
GET /dogs/1
{
"name" : "Buddy",
"type" : "Golden Retriever",
"color" : "redish-yellow"
}
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.
GET /dogs
"entries" : [
{
"name" : "Buddy",
"id" : "1",
"links" : {
"href" : "http://api.example.com/dogs/1"
}
},
{
"name" : "Ralph",
"id" : "2",
"links" : {
"href" : "http://api.example.com/dogs/2"
}
},
{
"name" : "Skippy",
"id" : "2",
"links" : {
"href" : "http://api.example.com/dogs/3"
}
}
]
Hope that helps.
Luke Stokes
Feb 23, 2012, 1:07:51 PM2/23/12
to API Craft
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.
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.
Richard Berger
Feb 24, 2012, 4:16:58 PM2/24/12
to API Craft
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?
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 :)
- 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 :)
Luke Stokes
Feb 26, 2012, 2:42:08 PM2/26/12
to API Craft
Ah yes, sorry for the mis-attribution, Daniel!
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.
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.
Richard Berger
Mar 4, 2012, 8:36:36 PM3/4/12
to API Craft
Dan:
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
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
Daniel Roop
Mar 4, 2012, 9:29:19 PM3/4/12
to api-...@googlegroups.com
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.
Ronan Quillevere
Feb 28, 2013, 9:45:51 AM2/28/13
to api-...@googlegroups.com
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.
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.
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.
Reply all
Reply to author
Forward
0 new messages