Re:Stop Designing Fragile Web APIs
by vog on Tuesday April 23, 2013 @11:13AM
(#5595605)
It is very important to also document what the API doesn't provide, in addition to what it provides.
If the documentation doesn't specify the sorting order, this means that the client must not make any assumptions on the sorting. The client either has to take the sorting as is (and trust the API provider to always use a userfriendly order), or has to re-sort the result on client side to stay in control.
A similar argument holds for the result set: If the API docs specify that there may be "additional fields", the client must be flexible enough to ignore unknown fields.
There is an important difference between being deliberately vague (being clear on what the API doesn't guarantee) and just being vague (sloppy documentation). The latter is of course a PITA, but I it is clear from the article that it's the former what the author had in mind.
If the documentation doesn't specify the sorting order, this means that the client must not make any assumptions on the sorting. The client either has to take the sorting as is (and trust the API provider to always use a userfriendly order), or has to re-sort the result on client side to stay in control.
A similar argument holds for the result set: If the API docs specify that there may be "additional fields", the client must be flexible enough to ignore unknown fields.
There is an important difference between being deliberately vague (being clear on what the API doesn't guarantee) and just being vague (sloppy documentation). The latter is of course a PITA, but I it is clear from the article that it's the former what the author had in mind.