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. Commented Jun 11, 2010 at 0:50
  • If you do automatic code generation of an API wrapper it makes the wrapper ugly. 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. 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 ++. 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. 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. 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. Commented Jun 14, 2010 at 10:47

You must log in to answer this question.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.