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.
-
seconded, this would make my life much easier– Matt S.Commented May 23, 2010 at 0:14
Add a comment
|
2 Answers
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.
answered May 25, 2010 at 7:00
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...)
answered May 23, 2010 at 1:28
-
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.– ColinDCommented May 23, 2010 at 1:48