my first thoughts on getting the count

[Benjamin Atkin]

First, I really enjoyed this. You covered a lot of ground in a short amount of time.

I think that adding /count would make it easily confusable with the resource identifier, plus there's the rare issue that there might be a resource named count. But it's not a big problem.

I think there's an easier solution, though. Show the count in the response for the collection url (example: /posts). If a big response with a list of resources isn't desired, allow specifying limit=0. If it's expensive to calculate the count, allow for a query option like ?include_count=true to be specified.

I'd like to see examples, though. I think it's fairly common to bundle up multiple counts for all items in the list if they're quickly available, for instance twitter has following and followers. This makes it so a special call for a count isn't needed.

One theme to your webinar was looking at what companies that have already built APIs have done and I think that's a great place to start. The next is to figure out which are the best to learn from. I think it depends on what kind of API is being built.

Ben

[Benjamin Atkin]

I forgot to mention up front that I was talking about the RESTful API Design webinar.

http://www.youtube.com/watch?feature=player_embedded&v=QpAhXa12xvU#!

[Brian Mulloy]

Hi Ben,

I think that's a solid approach to include count as meta-data in the
response.

In fact, there's probably an interesting pattern to include a
consistent set of metadata in each response with, as you mentioned,
switches to suppress.

It also bugs me a bit having a reserved word like count where the id
should be.

Hope you've been well. Good to hear from you.

-b

[KevBurnsJr]

I agree with including a count (or total) in the representation of
collections rather than giving count its own resource.
http://podcrazy.net/search.json?tag=news

I also agree that collection representations in an API should have
similar metadata.
Example:

GET /dogs?q=fido
Accept: application/json

{
offset: 0,
limit: 10,
total: 321,
q: "fido",
results: {
// <snip>
},
_links: {
next: "/dogs?q=fido&offset=10"
}
}



- Kev

[Brian Mulloy]

that's cool. maybe something like this explicitly grouping the
metadata:

{
"dogs": [
{"dog": {"name":"Fido"}},
{"dog": {"name":"Fido Jr."}},
{"dog": {"name":"Fido III"}}
],
"_metaData": {"count":3,"limit":10,"offset":0,"q":"fido"},
"_links": {"next": "/dogs?q=fido&offset=10"}

}

On Nov 11, 1:19 am, KevBurnsJr <kevburn...@gmail.com> wrote:
> I agree with including a count (or total) in the representation of

> collections rather than giving count its own resource.http://podcrazy.net/search.json?tag=news

[David Biesack]

On Friday, November 11, 2011 2:50:02 AM UTC-5, landlessness wrote:

that's cool. maybe something like this explicitly grouping the
metadata:

{
  "dogs": [
    {"dog": {"name":"Fido"}},
    {"dog": {"name":"Fido Jr."}},
    {"dog": {"name":"Fido III"}}
  ],
  "_metaData": {"count":3,"limit":10,"offset":0,"q":"fido"},
  "_links": {"next": "/dogs?q=fido&offset=10"}
}

so one could query

 GET /dogs?offset=0&count=0

to get just the count while also getting an empty collection.

Originally when I was watching the webcast, I thought

 GET /<resource>.count

as in

 GET /dogs.count

This simplifies things, as one need not get back both

the collection and the metadata and then have to look up

the count and throw away the empty collection.

(i.e. use count as a resource suffix).

Discussion points:

Is count special enough to elevate it's status in the API?

How often does one want to get just the count and not (a page of) the items?

 

[Arlo Belshee]

This representation structure is starting to go in a very similar direction to where we went with OData. There are some gotchas here that we only discovered after we’d released our first version – and are causing us to develop a new (lighter-weight) Json format.

 

I thought I’d share the problems we encountered in the hope that you can avoid them (and find your own).

 

First, we found the __ convention to be problematic (__metadata). The name worked well for access in JavaScript, but was not nearly as extensible as a real namespacing mechanism would have been. We are changing to real namespaces.

 

Second, as our resources got more complicated, we ended up with metadata strewn all over the place. For example, we support complex types (nested Json objects) and expanded relationships (more Json objects). To send type or link information for these, we ended up either having to build two parallel object graphs or toss __metadata nodes everywhere. Both are…unfortunate.

 

Currently, our best idea is to support templating for metadata (a bit like Json-LD does), and then define a syntax for tagging any name/value pair with metadata. Then we only use those tags in the places where we’re overriding defaults. This isn’t a perfect idea, but it works OK.

 

We also support metadata links (again similar to Json-LD), so that metadata can be shared between multiple requests (pulled in by reference).

 

Finally, it’s a good idea to place metadata first. This allows strongly-typed clients to read type information before they have to parse the values. That can reduce buffering.

 

That’s about all the unsolicited advice I’ll give. If you want to know more, please ask. I just want to avoid spamming you with info you don’t want.

 

Arlo

[Ed Anuff]

Very interesting stuff, thanks for sharing it.  Would love to hear more
about where you're going with your lightweight JSON format.

[Arlo Belshee]

We are currently putting together an annotated example of our design to date. It’ll probably be done Monday or Tuesday.

 

I’ll certainly send it to the group and ask for input then!

 

Arlo