The documentation isn't officially released yet, but I have some feedback anyway:
The API, I feel, should make more use of HTTP response codes. Not Found is 404, every other error is 500, which should generally be used only for a server-side error.
I would suggest using the following codes:
Invalid application, Invalid application permissions, invalid application signature - 401 Unauthorized
Access denied - 403 Forbidden
Throttled - 503 Service Unavailable (preferably WITH a Retry-After header!)
Invalid authentication header - 400 Bad Request
The other two, not found and internal server error, are appropriate as 404 and 500 respectively :-)
The reason for this is ease of client error handling, without keeping a set of strings that may be returned, particularly if those strings wind up being localised. In particular, receiving a 500 would mean you just need to wait a bit then retry, while a 401 means you need to flag to the operator that there's a credentials problem, a 403 means the operator needs to go to layer 8 to fix the issue, and a 503 means you should increase your per-request delay.
Most notable is that all 4xx errors are not recoverable, and require operator intervention, but all 5xx errors are recoverable with time. In particular, getting a 503 with a Retry-After would let a client fine tune its back-off behaviour.
|
|
|
Hi,
Sorry if this is a repeat report, but if one fetches, for example: http://us.battle.net/api/wow/realm/status?realm=Gurubasho One would expect to get back something like {'realms':[]}, or possibly an error. Instead, all realms are returned. Also, while I'm here, I'm passing "Accept-Encoding: gzip" and getting back well formed gzipped data, so that's good news, thanks! |