what best practice return error in restful? in http status code 4xx or in response body? if first, how can int retrofit?
your apis or rest methods need intuitive
first, developers learn write code through errors. "test-first" concepts of extreme programming model , more recent "test driven development" models represent body of best practices have evolved because such important , natural way developers work.
from perspective of developer consuming web api, @ other side of interface black box. errors therefore become key tool providing context , visibility how use api.
secondly, in addition when they're developing applications, developers depend on well-designed errors @ critical times when troubleshooting , resolving issues after applications they've built using apis in hands of users.
how think errors in pragmatic way rest?
let's take @ how 3 top apis approach it.
facebook
no matter happens on facebook request, 200 status code - ok. many error messages push down http response. here throw #803 error no information #803 or how react it.
twilio
twilio great job aligning errors http status codes. facebook, provide more granular error message link takes documentation. community commenting , discussion on documentation helps build body of information , adds context developers experiencing these errors.
simplegeo
provides error codes no additional value in payload. couple of best practices
use http status codes use http status codes , try map them cleanly relevant standard-based codes.
there on 70 http status codes. however, developers don't have 70 memorized. if choose status codes not common force application developers away building apps , on wikipedia figure out you're trying tell them.
therefore, api providers use small subset. example, google gdata api uses 10 status codes, netflix uses 9, , digg, 8.
how many status codes should use api?
when boil down, there 3 outcomes in interaction between app , api:
everything worked application did wrong api did wrong start using following 3 codes. if need more, add them. shouldn't go beyond 8.
200 - ok 404 - not found 500 - internal server error if you're not comfortable reducing error conditions these 3, try picking among these additional 5:
201 - created 304 - not modified 400 - bad request 401 - unauthorized 403 - forbidden (check out wikipedia entry http status codes.)
it important code returned can consumed , acted upon application's business logic - example, in if-then-else, or case statement.
make messages returned in payload verbose possible
verbose.
use plain language descriptions.
add many hints api team can think of what's causing error.
i highly recommend add link in description more information, twilio does
taken - https://blog.apigee.com/detail/restful_api_design_what_about_errors
other usefull links http://www.restapitutorial.com/httpstatuscodes.html
Comments
Post a Comment