2

"number" is an very ambiguous term. Integral or non-integral?

For developers in more dynamically-typed languages like JavaScript, this is not an issue; but when using more statically-typed languages like C#, developers need to know when an int or long should be used, as opposed to a double.

It would be helpful if values that can be non-integral were more clearly indicated.

Update:

Yes, I understand that you are returning a "number" in JSON, so technically the spec is correct. But what good does that do your audience?

Should I make every object field and database column a float so it doesn't break unexpectedly because I guessed wrong what datatype I should use? Sure, I can guess, and in most cases guess correctly, but is that really the best thing possible?

"number" is of questionable value to all but the most trivial applications of the API, and downgrading the spec because of the limitations of transport is a mistake in my opinion.

Improve this question
6
  • On the flip side, what good does decimal do a developer working in javascript? float, real, double, etc. are all constructs of particular languages; number at least has a concrete meaning in context.
    – Kevin Montrose
    Commented Jun 1, 2010 at 21:53
  • @kevin - I think we have a disconnect here. I am not suggesting that you CHANGE the type as listed, I am suggesting that an additional hint indicating whether the field is integral or not for those not working in JS - which is MOST of us.
    – Sky Sanders
    Commented Jun 1, 2010 at 22:43
  • decimal doesn't exist in Java as a primitive type; real is pretty vague; lets not even get started on strictfp. I'm just saying, its a lot more complicated than you're making it out to be. integral/non-integral even raises some length issues (dates > 32 bits, most everything else <= 32 bits; signed/unsigned is another question).
    – Kevin Montrose
    Commented Jun 1, 2010 at 22:56
  • @kevin - it is not complicated at all from my perspective: the single concern is whether to declare all 'number' fields in the api as double/float to accomodate the possible values represented by 'number' or add a note to the field description indicating that there will be no freakin decimal points in the value. Should an API spec make people guess? My experience is no, an API spec should server to remove amibiguities.
    – Sky Sanders
    Commented Jun 1, 2010 at 23:47
  • Your perspective is colored by a single use case; simply specifying the presence of a decimal point is the wrong thing to do here. You're basically proposing making the spec incorrect in the pursuit of fewer ambiguities. I do agree that number needs to be made more specific, but doing so is non-trivial and accordingly will take some time.
    – Kevin Montrose
    Commented Jun 2, 2010 at 0:32
  • @kevin - we seem to be arriving at the same place, regardless of the route. thanks for taking the time to talk about it.
    – Sky Sanders
    Commented Jun 2, 2010 at 1:31

1 Answer 1

Reset to default
2

We're using number in the JSON sense of the word. number in that context does cover all the data types we're returning.

I suppose it could be tightened up a bit, though...

Descriptions of the types of number coming back are now part of the /help docs.

Improve this answer

You must log in to answer this question.

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