8 ms·
The Good, the Bad, and the Ugly of REST APIs
- regularfry 15y agoSpeaking as someone who's currently building a cloud API, this makes a lot of sense.
- jschrf 15y agoI love the simplicity provided by a good REST API. ESRI's REST platform is a good example of a nice, clean API. Very easy to diagnose and resolve issues, especially with tools like Fiddler. A really nice feature to have in a REST API is the ability to run operations in an HTML form. With this, you can re-run requests in the browser and tweak parameters to help you diagnose issues. Very useful.
- tlrobinson 15y agoI prefer Charles: http://www.charlesproxy.com/ http://www.charlesproxy.com/
- jschrf 15y agoLooks good. I'll give it a try, thanks. One problem I have is dealing with viewing my Comet connection (long-lived XHR). I stream JSON to the browser and Fiddler picks up and is able to display all this data, but prevents it from being received by the browser. Would be nice to not have this problem so I can see my JSON events in Fiddler and in my UI.
- terinjokes 15y agoCan you let us know if you had better luck with Charles?
- jschrf 15y agoSure thing.
- georgefox 15y agoHave you tried tcpTrace (http://www.pocketsoap.com/tcptrace/ http://www.pocketsoap.com/tcptrace/)? It's dead simple, so I wonder if that may help. I haven't ever used it with long-lived XHR, so I can't say it'll work, but it's a free, 224 KB standalone, so it can't hurt to try.
- jimbobimbo 15y agoCharles is awesome. We used it to debug connectivity with some third-party web service over HTTPS -- absolutely worth its money.
- cpeterso 15y agoAbsolutely. Charles can sniff SSL by acting as a man-in-the-middle Certificate Authority. Very clever!
- stevenp 15y ago"I know you love {JSON,XML} and you think everyone should be using {JSON,XML} and that the people who use {XML,JSON} are simply stupid." Does anyone love XML and hate JSON?
- georgefox 15y agoI wouldn't say love and hate, but I've met people who like XML because it's familiar and don't care for JSON because to them it's foreign.
- baddox 15y agoI'm sure there are some programmers who know their way around their favorite XML library in their favorite language and would refuse to learn another.
- irahul 15y agoBut there isn't much to learn while parsing JSON. It nicely maps to high level languages. It does make your knowledge of XML useless, but it doesn't has the cognitive overhead of learning something which takes time and effort.
- georgemcbay 15y agoI don't love XML or hate JSON, but part of my job involves writing Flash/AVM1 (ActionScript 2) code that runs on slow CPUs (yes, feel free to pity me). I can get reasonable performance out of large XML results because the XML is parsed inside the Flash VM by native code. There is no such luxury for JSON, so I have to resort to writing hacky non-compliant "JSON parsers" in ActionScript that are optimized for specific data sets (because the slow-CPU/Flash-AVM1 combo means a true compliant JSON parser for the full API result is just way too slow). So, while I may much rather be using JSON (or better yet, protobufs of thrift) for everything in a totally different environment, I do appreciate APIs giving me XML results because of my specialized situation.
- epynonymous 15y agoright, i can't think of anyone that prefers xml over json-- xml seems too bloated, dom and sax parsers require lots of code to walk trees compared to just a single json parse call and then you can just directly access things in an object. though i have had to write several json decoder/encoders for special objects. for my internal rest apis, the only response format i provide is json, this is for mvp purposes. though i will add xml when i publicize these apis.
- vyrotek 15y agoMap your API model to the way your data is consumed, not your data/object model I'm glad this was brought up. I feel I'm constantly battling with myself on this issue. The purist in me always wants to create REST endpoints that return just the minimum info you'd expect from that URL which represent my model perfectly. The result is requiring customers to call the service a lot. But sometimes if you take a step back and think about how it will be consumed you can really do your consumers/customers a favor. Although, if not carefully thought through you could end up doing more 'work' and returning data that is always discarded from the response.
- joelhaasnoot 15y agoThis thinking can however also be taken to far. The Dutch Railways recently released an API for all their trip planning, live departures and pricing info. Unfortunately, it's mainly a way to get at the API their apps call: it's all presentation based. For instance, up until recently there was no way to tie a certain train service listed in a given trip to the same service in the live departure endpoint. It's also still not possible to tie a train service to its schedule. They've taken their API and made it all consumer-oriented and it's gone overboard.
- jimbobimbo 15y ago"And while you're at it, don't use HTTP authentication either. Use signed queries that authentication each API call individually." What is the problem with using digest auth with proper request counter (nc) incrementing done over HTTPS?
- boucher 15y agoWhat's the problem with HTTP Basic auth over HTTPS?
- bbsabelli 15y agoCost?
- daredevildave 15y agoIsn't "signed queries" the same as 2-legged OAuth?
- stanleydrew 15y agoThere's nothing wrong with it or with HTTP Basic Auth over HTTPS either for that matter. The author doesn't seem to understand that HTTP Basic/Digest Auth is effectively exactly what he wants: a signed request that authenticates each API call. The fact that it goes in an HTTP header rather than some query parameter or something in the request body is only relevant in the case that users of your API don't have the ability to manipulate headers. This is a vanishingly small set of users. Whether they know how to do it or not is another matter.
- psadauskas 15y agoThe problem with it is that you can't cache it in an intermediate server, like Varnish or Squid. You have to `Vary` on the authentication header, and with a counter that increments every request, it invalidates the cache every request. Better is Basic over SSL, since the Authentication header never changes.
- credo 15y ago>>And while you're at it, don't use HTTP authentication either. Use signed queries that authentication each API call individually. Beyond server-server api calls and authentication, I'm curious to know what folks think about authentication and individual-user client apps making api calls to a server. If you build a web service whose REST apis are only intended to be consumed by customers of your $0.99 mobile app, one option is to use no authentication at all. This means that a third-party may potentially write another $0.99 app that "steals" your web-server resources. Has this been a problem and what (if any) schemes (e.g. digest auth, facebook login etc.) have you used to mitigate the problem. (facebook login etc. doesn't fully address the problem unless you can distinguish between facebook users who have purchased the app and facebook users who haven't purchased the app )
- jimbobimbo 15y agoWhy not to use client cert and HTTPS or HTTP digest authentication with same password across clients? In order for third-party to create their client, they have to go through reversing procedure, which would be unlawful.
- derefr 15y agoYou expect that the third-party co-opting your server resources would be in US legal jurisdiction?
- jimbobimbo 15y agoI expect this will give me firmer grounds whenever I need to send DMCA takedowns.
- epynonymous 15y ago"Meaningful error messages help a lot" the beauty of rest is that you piggy back off the error codes of the http protocol, e.g. 403 forbidden, 404 page not found, 500 internal server error. of course you could always add text in the response providing more detail, but i argue that this is not very helpful in all cases, what can you as the api consumer do if the server is barfing back something cryptic (503)? the use case i can think of is for an errant parameter in the request, i'm a firm believer of the client app doing field validation, of course that doesn't absolve the server from having to also do it. but instead of providing a 500 (internal server error), i think there could be something more meaningful like a 400 (bad request) followed by some response parameter with more detailed information like "your address field contains a float". the example given for authentication is a poor choice, there are security reasons why you would want to be vague, returning the fact that the password is mistyped only tells the consumer of the api that this user exists, please hack me. the one thing i hate about rest is how to document the endpoints and the various http statuses that could be returned, if someone could generate a script that could help me here (for python) that would be appreciated.
- epochwolf 15y agoRails uses 422 for invalid input. Which wikidepia says[1]: Unprocessable Entity (WebDAV) (RFC 4918) The request was well-formed but was unable to be followed due to semantic errors 1: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
- neeleshs 15y agoTo me, throttling and chatty APIs seem to be orthogonal. These apply to REST or SOAP or any other API. EDIT: I'm wrong, chatty is specific to REST.
- j_baker 15y agoFailing to realize that a 4xx error means I messed up and a 5xx means you messed up More often than not, this seems to boil down to bad error handling than it does lack of understanding.
- extension 15y agoREST is good, SOAP is bad The irony is that SOAP is a lot closer to being RESTful than RPC-over-HTTP aka "REST API", because SOAP actually attempts to have a uniform interface driven by hypertext (WSDL). That doesn't mean it's easier, but REST is not supposed to be easy.