Take the 2-minute tour ×
Stack Apps is a question and answer site for apps, scripts, and development with the Stack Exchange API. It's 100% free, no registration required.

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?

share|improve this question
add comment

2 Answers 2

up vote 2 down vote accepted

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

share|improve this answer
    
Because it's a single result, I'd say. –  ColinD Jun 11 '10 at 0:50
    
If you do automatic code generation of an API wrapper it makes the wrapper ugly. –  Robert Love Jun 11 '10 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 Jun 11 '10 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 Jun 14 '10 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 Jun 14 '10 at 22:28
add comment

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.

share|improve this answer
    
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 Jun 11 '10 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 Jun 14 '10 at 10:47
add comment

You must log in to answer this question.

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