The recommendations seem a little weak for me.
1. Most REST services can not be accessed just by typing the url in the
browser. What about security tokens? Or header values? Or sending PUT, POST,
PATCH or DELETE?
2. No serious developer will use just the browser and not any other tools. This
is plain dumb. We use a bunch of tools for dev and test, from packet sniffers
and REST testers, to javascript consoles and log analyzers.
3. REST services should be documented, so the developer knows for sure what 404
means in each case and has the correct urls for every resource :)
Sent from my LG Mobile
------ Original message------From: Bert VerheesDate: Sun, Jan 18, 2015 9:46
AMTo: openehr-technical at lists.openehr.org;Subject:Re: CRUD Restlet For
information:
See the recommendations by Ethan Cerami: Specialties: Cancer genomics,
bioinformatics, scientific computing, software engineering, project
management.
https://www.linkedin.com/in/ecerami
http://www.oreilly.com/pub/au/806
Read:
http://archive.oreilly.com/pub/post/restful_error_handling.html#__federated=1
Quoting:
Conclusion:
Human Readable Error Messages: Part of the major appeal of
REST based web services is that you can open any browser, type in the
right URL, and see an immediate response -- no special tools needed.
However, HTTP error codes do not always provide enough information. For
example, if we take option 1 above, and request and invalid book ID, we
get back a 404 Error Code. From the developer perspective, have we
actually typed in the wrong host name, or an invalid book ID? It's not
immediately clear. In Option 3 (DAS), we get back a blank page with no
information. To view the actual error code, you need to run a
network sniffer, or point your browser through a proxy. For all these
reasons, I think Option 4 has a lot to offer. It significantly lowers
the barrier for new developers, and enables all information related to a
web service to be directly viewable within a web browser.
Application Specific Errors: Option 1 has the disadvantage of not being
directly viewable within a browser. It also has the additional
disadvantage of mapping all HTTP error codes to application specific
error codes. HTTP status codes are specific to document retrieval and
posting, and these may not map directly to your application domain. For
example, one of the DAS error codes relates to invalid genomic
coordinates (sequence coordinate is out of bounds/invalid). What HTTP
error code would we map to in this case? Machine Readable
Error Codes: As a third criteria, error codes should be easily readable
by other applications. For example, the XooMLe application returns back
only human readable error messages, e.g. "Invalid Google API key
supplied". An application parsing a XooMLe response would have to search
for this specific error message, and this can be notoriously brittle
-- for example, the XooMLe server might simply change the message to
"Invalid Key Supplied". Error codes, such as those provided by DAS are
important for programmatic control, and easy creation of exceptions. For
example, if XooMLe returned a 1001 error code, a client application
could do a quick lookup and immediately throw an InvalidKeyException.
Based on these three criteria, here's my vote for best error handling
option:
Use HTTP Status Codes for problems specifically related to HTTP,
and not specifically related to your web service.
When an error occurs, always return an XML document detailing
the error.
Make sure the XML error document contains both an error code,
and a human readable error message. For example:
<error>
1001
<error_msg>Invalid Google API key supplied</error_msg>
</error> By following these three simple practices, you can make
it significantly easier for others to interface with your service,
and react when things go wrong. New developers can easily see valid and
invalid requests via a simple web browser, and programs can easily (and
more robustly) extract error codes and act appropriately. The
Amazon.com web services API follows the approach of returned XML document
can specify an ErrorMsg element.
XooMLe also follows this approach. (XooMLe provides a RESTful API
wrapper to the existing SOAP based Google API).
Another approach is by DAS ( Distributed Annotation System) which always
returns 200 if there was no HTTP-error and has error information in the
HTTP-header, which is less favorable, because it is not human readable, as a
browser does not display the HTTP-header.
---
End Quoting
Best regards
Bert
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/8d788913/attachment.html>
