Tell me more ×
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.
up vote 4 down vote favorite
1

I'd like to see documentation on what fields may not be included in responses or, alternatively, which fields are guaranteed to be included. Currently it's a little confusing because some fields may be left out while others may be returned as an empty string or array and I don't see any clear pattern there.

share|improve this question
seconded, this would make my life much easier – Matt S. May 23 '10 at 0:14

2 Answers

up vote 2 down vote accepted

Returned parameters now have an optional field in the documentation (example) that indicates whether they should always be present.

For the duration of the beta at least (not going to guarantee 1.0+, there are some performance implications) we're actually enforcing this. If a response we're to somehow not have a required field set, an error will occur which will show up in our logs.

Accordingly, if "optional": false is on a returned field feel free to really assume its always there.

share|improve this answer
Nice one! Thanks – YOU May 25 '10 at 7:18
Great, thank you! – ColinD May 25 '10 at 15:19
up vote 0 down vote

This would be a good idea for the simple wrappers that want to just assume a certain value will be there.

But for a serious application, there should still be a check to make sure a value is included even if it is "guaranteed" to be - otherwise, I would argue that the app has very poor error handling.

After all, what happens when the spec changes? (Keep in mind the API is still in beta...)

share|improve this answer
I think it's entirely reasonable to expect certain values to be included. I'd like to document in the wrapper I'm working on whether or not users need to check for a null when retrieving a certain property or not. As far as the API changing: of course it can change, and I would expect to (possibly) have to update my wrapper if it does. Nothing is final until a locked-in API is available, but it would still make sense to document this for the API as it is now. Or even just to document it once 1.0 is ready... I'd like to know sooner, but I can live with that too. – ColinD May 23 '10 at 1:48

You must log in to answer this question.

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