<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On 24 July 2014 21:14, Petter Goksøyr Åsen <span dir="ltr"><<a href="mailto:petter.goksoyr.asen@kul.oslo.kommune.no" target="_blank">petter.goksoyr.asen@kul.oslo.kommune.no</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">As for error returns: there is nothing wrong with returning a proper HTTP status code<br>
AND  a human/machine-readable error message. In fact, that's what I would go for.<br>That way, the client can short circut just by checking the status code, or parse the response<br>if it needs to give some feedback ...<br>
<br>For example:<br>curl -i -X GET /rest/biblionr/1235<br>Returns:<br>HTTP/1.1 404 Not Found<br>Date: Thu, 24 Jul 2014 09:11:07 GMT<br>Content-Type: application/json; charset=utf-8<br>Transfer-Encoding: chunked<br><br>{ "error": "no record with biblilonumber 12345 found"}<br>
<br>Regards<br><div class="">Petter Goksøyr Åsen<br>Deichmanske bibliotek / Oslo Public Library<br></div></blockquote><div><br></div><div><br></div><div>Yes, I think it comes down to a matter of preference. I can see good reasons to go either way on that. Going the other way is a little simpler to manage for me. And I'm certain some folks will feel more strongly about it than I do.</div>
<div><br></div><div><br></div><div><br></div><div><br></div></div><br><div class="gmail_quote">On 24 July 2014 18:59, David Cook <span dir="ltr"><<a href="mailto:dcook@prosentient.com.au" target="_blank">dcook@prosentient.com.au</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-AU" link="#0563C1" vlink="#954F72"><div><p class="MsoNormal">
<a name="147672b455de0982__MailEndCompose"><span style="font-size:11pt;font-family:Calibri,sans-serif">Hey Reed:<u></u><u></u></span></a></p><p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif"><u></u> <u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif"><span>1)<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">      </span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif">I’ve wondered a bit about that as well. So far, everything I’ve looked at appears to handle PUT and DELETE just fine, but I’m definitely a bit wary of running into odd problems like that. I’d love to hear more about that from others.</span></p>
</div></div></blockquote><div><br></div><div>I think it's not super likely that PUT and DELETE would be genuine problem on average. I probly worry too much.</div><div> </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-AU" link="#0563C1" vlink="#954F72"><div><p><span style="font-size:11pt;font-family:Calibri,sans-serif"><u></u><u></u></span></p><p><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif"><span>2)<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">      </span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif">Agreed. I think POST for writes and GET for reads is the norm. <u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif"><span>3)<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">      </span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif">Agreed. Returning HTML sounds like a horrible idea. I’d say XML or JSON.<u></u><u></u></span></p>
<p><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif"><span>4)<span style="font-style:normal;font-variant:normal;font-weight:normal;font-size:7pt;line-height:normal;font-family:'Times New Roman'">      </span></span></span><u></u><span style="font-size:11pt;font-family:Calibri,sans-serif">Could you clarify a bit more about what you mean a bout “API level exceptions”? When I first read that, I thought “he must be mad!” Then I started to think that perhaps you were talking about application level exceptions? Like…”borrowernumber” not found or something like that? I did something similar. When they didn’t provide the borrowernumber, I returned a successful response with an error message. I figure it’s more useful than a “bad request” http response or something of that sort. I suppose the only downside is that you need to know to check for the error in the response. So…it is tempting to use HTTP error responses instead.</span></p>
</div></div></blockquote><div><br></div><div>Petter's example is probably a good illustration.</div><div><br></div><div>But, no, I take it to the extreme edge of reasonableness. Any application level error I can trap is wrapped in a message which I deliver to the client in an HTTP success response.</div>
<div><br></div><div>I should note at this point I'm doing this all in Python which makes that simpler.</div><div><br></div><div>My thinking is that I want to reserve HTTP errors for transport failures instead of application failures/errors.</div>
<div><br></div><div>And it does seem to simplify the way I think about the client/javascript layer of the application. All handled responses are dealt with in one place if they're successful HTTP requests and anything else is a generic catastrophe.</div>
<div><br></div><div>-reed</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-AU" link="#0563C1" vlink="#954F72"><div><p><span style="font-size:11pt;font-family:Calibri,sans-serif"><u></u><u></u></span></p><div class=""><p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif">David Cook<u></u><u></u></span></p><p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif">Systems Librarian<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif">Prosentient Systems<u></u><u></u></span></p><p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif">72/330 Wattle St, Ultimo, NSW 2007<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif"><u></u> <u></u></span></p></div><p class="MsoNormal"><b><span lang="EN-US" style="font-size:11pt;font-family:Calibri,sans-serif">From:</span></b><span lang="EN-US" style="font-size:11pt;font-family:Calibri,sans-serif"> <a href="mailto:koha-devel-bounces@lists.koha-community.org" target="_blank">koha-devel-bounces@lists.koha-community.org</a> [mailto:<a href="mailto:koha-devel-bounces@lists.koha-community.org" target="_blank">koha-devel-bounces@lists.koha-community.org</a>] <b>On Behalf Of </b>Reed Wade<br>
<b>Sent:</b> Wednesday, 23 July 2014 8:09 PM<br><b>To:</b> <a href="mailto:koha-devel@lists.koha-community.org" target="_blank">koha-devel@lists.koha-community.org</a></span></p><div class=""><br><b>Subject:</b> Re: [Koha-devel] RFC: /svc/ API<u></u><u></u></div>
<p></p><p class="MsoNormal"><u></u> <u></u></p><div><div><p class="MsoNormal"><u></u> <u></u></p></div><div><p class="MsoNormal">Just to add my bits regarding rest style APIs because I've been making a lot of those lately:<u></u><u></u></p>
</div><div><div class="h5"><div><p class="MsoNormal"><u></u> <u></u></p></div><div><p class="MsoNormal"><u></u> <u></u></p></div><div><p class="MsoNormal">- sticking with GET and POST may simplify things because they're just a lot more typical and you're less likely to run into odd problems with less well tested lib and proxy support<u></u><u></u></p>
</div><div><p class="MsoNormal">- a great rule of thumb is POST for writes and GET for reads; this makes it intentionally harder to compose a url that accidentally writes anything<u></u><u></u></p></div><div><p class="MsoNormal">
- avoid emitting HTML, the cool kids are letting the browser do all the work now<u></u><u></u></p></div><div><p class="MsoNormal"><u></u> <u></u></p></div><div><p class="MsoNormal">Some folks will not like the next bit of advice because it's not pure REST. I like to never return http error responses for API level exceptions. Instead I like to provide a "success" boolean value in the json response and a text explanation in a separate variable.<u></u><u></u></p>
</div><div><p class="MsoNormal"><u></u> <u></u></p></div><div><p class="MsoNormal">-reed<u></u><u></u></p></div><div><p class="MsoNormal"><u></u> <u></u></p></div><div><p class="MsoNormal"><u></u> <u></u></p></div></div></div>
</div></div></div></blockquote></div><br></div></div>