2

Why does the stats API Call return an Array instead of just an object?

Example Response:

{
  "statistics": [
    {
      "total_questions": 723903,
      "total_unanswered": 114097,
      "total_answers": 2002231,
      "total_comments": 2838514,
      "total_votes": 7046950,
      "total_badges": 725485,
      "total_users": 260132,
      "questions_per_minute": 1.89,
      "answers_per_minute": 3.79,
      "badges_per_minute": 1.45,
      "api_version": {
        "version": "0.8",
        "revision": "2010.6.9.1"
      },
      "display_name": "Stack Overflow"
    }
  ]
}

Instead of:

{
  "statistics": 
    {
      "total_questions": 723903,
      "total_unanswered": 114097,
      "total_answers": 2002231,
      "total_comments": 2838514,
      "total_votes": 7046950,
      "total_badges": 725485,
      "total_users": 260132,
      "questions_per_minute": 1.89,
      "answers_per_minute": 3.79,
      "badges_per_minute": 1.45,
      "api_version": {
        "version": "0.8",
        "revision": "2010.6.9.1"
      },
      "display_name": "Stack Overflow"
    }
}

Is there plans to return more than one element ever?

Improve this question

2 Answers 2

Reset to default
2

Symmetry mostly. Every other method returns a collection, why should /stats be a one off?

Improve this answer
5
  • Because it's a single result, I'd say.
    – ColinD
    Commented Jun 11, 2010 at 0:50
  • If you do automatic code generation of an API wrapper it makes the wrapper ugly.
    – Robert Love
    Commented Jun 11, 2010 at 1:35
  • @Robert - automatic code generation is neat, but you can't really expect it to be as good as a handcrafted API. Accordingly, changes meant solely to improve the automatic code generation case aren't really all that compelling.
    – Kevin Montrose
    Commented Jun 11, 2010 at 1:51
  • @robert - if you look at generated api consumer code as a core library and the bulk of your code and then wrap your wrapper with purty code the story becomes a bit more compelling. Kevin ++.
    – Sky Sanders
    Commented Jun 14, 2010 at 10:50
  • I have used code generation to make sure parameters and properties have nice XML Comments, and that I have not missed something. I have then modified it to make it look pretty from there. If an entire new API Method was introduced I would generate it initially as well.
    – Robert Love
    Commented Jun 14, 2010 at 22:28
3

I have found that the uniformity of having all of the methods return arrays has made writing a library much easier. Of course if it is a call (like the stats method) which always returns just one result, you don't have to expose it as a list to the API consumer. I don't have any experience with code generation and web APIs so I can't speak to that.

Improve this answer
2
  • It's fine for most methods to return an array, because they all potentially return multiple results. Except statistics. I don't expose it as a list in my library, but I can certainly say that it being an array doesn't make things any easier for me. If no wrapper library is going to expose it as a list, why should the API itself expose it as such? It really doesn't make sense to me.
    – ColinD
    Commented Jun 11, 2010 at 11:59
  • ++ for 'package it howz you likes it' @ColinD - consistent api calls, or symmetry as kevin says, make consumption less complex in my experience. which is a good thing.
    – Sky Sanders
    Commented Jun 14, 2010 at 10:47

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .