> Also, the date of the post you reference is from ~ 2003 The Rest protocol is very old, maybe 15 years, and hasn't changed much, so are some recommandations. I don't know from which date the recommandation is to use HTTP- status for application error handling. I don't think that should be an argument.
And I am not writing client software, so I do not have to follow Api's from others. I am offering API's. I think a client is best served with an own defined error-handling instead of using the error-handling of another layer which is designed for other reasons. This argument was also in that document. I was just not sure if my choice was a good one, that was, for me, the reason for the discussion. But also on private level I got recommandations to follow my own idea, and I also found some supporting links. An application can have own error-handling needs. There was an example in that document. Similar examples I have too, where the mapping to the HTTP number schema feels unnatural, or by far too rudimentory. Being contra-intuitive in application API's is something to avoid, in my opinion. For example, saying that a resource is not available is a poor API's choice. Applications can be in need for a much more complex schema of errors, and it is good if an hierarchical system is possible. Why is a requested resource not available? Is it locked by the database? Has it ever been available, is it tomorrow available, has it brought to an archive system which needs an other Url or method, has the call been routed to another service or server, and is there something the matter? Just examples. I was looking at the PayPal API about authentication, they had defined over hundred things that can go wrong in an authentication-process. This needs a fine grained and extensible error-handling. Another reason is that, for example, the 404 will also be thrown for HTTP-technical reasons, inside Restlet, it is used for other reasons. It is confusing for a client with a 404 for application-reasons which need a entirely other action to be resolved. This was, I thought, also an argument from the link I posted. Anyway, I made my choice, and with support from some important people in my activity-context, so I follow that way. But thanks again for your arguments, they gave me something to think about. Bert. Op zondag 18 januari 2015 heeft pablo pazos <pazospablo at hotmail.com <javascript:_e(%7B%7D,'cvml','pazospablo at hotmail.com');>> het volgende geschreven: > But the recommendations you posted are built over false arguments, like > the #1. in my list on the previous message. > > Also, the date of the post you reference is from ~ 2003 ... > > IMO the bad news is you will not be able to use a lot of APIs that follow > principles and conventions you don't like, like the EHRScape ;) > > -- > Kind regards, > Eng. Pablo Pazos Guti?rrez > http://cabolabs.com <http://cabolabs.com/es/home> > <http://twitter.com/ppazos> > > Subject: Re: CRUD Restlet > > The point for me is separation of transport layer and application layer, > and each domain has its own errorhandling. > > I have made my choice. And it seems I am not the only one on the world > with this choice, which is good news > > thanks > Bert > > > pazospablo at hotmail.com schreef op 18-1-2015 om 19:52: > > 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 Verhees > > *Date: *Sun, Jan 18, 2015 9:46 AM > > *To: *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 > > > -- *This e-mail message is intended exclusively for the addressee(s). Please inform us immediately if you are not the addressee.* -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/17134ad5/attachment-0001.html>
