When REST isn't Good Enough • Hacker News Board

Re: When REST isn't Good Enough

#21

Post by mixedbit » Tue, Nov 20, 2012, 6:05 PM UTC

pixie_ wrote: post #5

I don't like REST. Making a call to a server should be like calling a function anywhere else - you have your parameters and return value. In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves. It's a much better design to combine all your parameters in one place and keep things simple, for example - REST version: UPDATE /course/324234 { description: "This is a level 1…

IMO the biggest benefit of REST vs RPC is reduced coupling between the client and the server. With RPC client needs to be explicitly aware of all methods and parameters that the server supports. With well designed REST interface this is not the case, you can have a generic client that does not need to be explicitly coded to support the specific service. REST interfaces are more difficult to design than RPC interfaces, but they are also more elegant and simpler. Roy Fielding (REST father) argues that elegant and simpler != easier.

Re: When REST isn't Good Enough

#22

Post by waffle_ss » Tue, Nov 20, 2012, 6:05 PM UTC

The title should add "by itself" at the end, as they are still using REST - just adding client libraries.

Re: When REST isn't Good Enough

#23

Post by MatthewPhillips » Tue, Nov 20, 2012, 6:05 PM UTC

bguthrie wrote: post #10

Note that this isn't a critique of the REST architectural style; rather, it documents their decision to prefer supplying clients with prebuilt libraries rather than a public API that their respective language communities can use to build their own. You could read the source to any one of their client libs and infer the rough structure of their services, so it's not all that private; they're simply choosing to leave w…

I have no knowledge of what BrainTree does, but if I'm picking a service with an API, I'm picking the one that is easiest to learn (preferably there is little that needs to be learned), I'm not picking one that requires me to switch languages -- or just as bad, locks me into one of a few languages I'm currently using.

Re: When REST isn't Good Enough

#24

Post by MatthewPhillips » Tue, Nov 20, 2012, 6:11 PM UTC

e28eta wrote: post #18

arethuza wrote: post #14

Earlier quoted context omitted.

"require a lot of orthogonal boilerplate to even make the requests properly" What kind of boilerplate would that be? For me one of the big advantages of a RESTful interface is that they are really easy to call from cURL without much need for building up a complex context.

I found the translation between native code and a REST API to be what I'd call boilerplate. You need to build a URL, build the request (usually converting some model object into JSON), make the request in a non-blocking fashion, receive and parse the response into either a successful response, probably converting JSON back into a model object, or a failed response, which needs to be mapped to some native representati…

Except company B uses a single callback, returning an object that contains an error code when not successful. Company C uses a blocking library, and requires you to pass in your model object as a dictionary. See where I'm going with this?

Re: When REST isn't Good Enough

#25

Post by bct » Tue, Nov 20, 2012, 6:15 PM UTC

pixie_ wrote: post #5

I don't like REST. Making a call to a server should be like calling a function anywhere else - you have your parameters and return value. In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves. It's a much better design to combine all your parameters in one place and keep things simple, for example - REST version: UPDATE /course/324234 { description: "This is a level 1…

> Making a call to a server should be like calling a function anywhere else

You can make calling a function on a remote machine look and seem (superficially) like calling a local function, but they will never have similar behaviour. A network is very different from a motherboard.

http://www.tbray.org/ongoing/When/200x/2009/05/25/HTTP-and-t...

Re: When REST isn't Good Enough

#26

Post by KrisJordan » Tue, Nov 20, 2012, 6:22 PM UTC

Braintree isn't the only HTTPS API a developer will consume. Rather than bury the knowledge of HTTPS best practice in the black box of a library, why not exemplify it in language-specific examples of plain-old REST API documentation?

If the boilerplate for manually getting an SSL connection right in a given language is that obtuse, the "just use our library" pitch is even more compelling.

All this said, I have used Braintree's libraries and they are extremely well executed.

Not exposing REST API documentation externally (it surely exists internally, right?) just feels like a cop out.

(An argument I'm surprised was left out: it's easier for support staff to work with customers integrating with a good library than some home rolled REST client. I can imagine this to be true, but maybe a case of premature optimization if the majority of big API players expose and document their REST APIs anyway?)

Re: When REST isn't Good Enough

#27

Post by pixie_ » Tue, Nov 20, 2012, 6:25 PM UTC

smacktoward wrote: post #17

pixie_ wrote: post #5

I don't like REST. Making a call to a server should be like calling a function anywhere else - you have your parameters and return value. In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves. It's a much better design to combine all your parameters in one place and keep things simple, for example - REST version: UPDATE /course/324234 { description: "This is a level 1…

Congratulations, you just invented JSON-RPC ( http://www.jsonrpc.org/ ).

I'm not saying how the parameters or return values should be formatted other than the fact they're in JSON format. JSON-RPC requires you to conform to their specifications.

Re: When REST isn't Good Enough

#28

Post by bct » Tue, Nov 20, 2012, 6:31 PM UTC

pixie_ wrote: post #27

smacktoward wrote: post #17

Earlier quoted context omitted.

Congratulations, you just invented JSON-RPC ( http://www.jsonrpc.org/ ).

I'm not saying how the parameters or return values should be formatted other than the fact they're in JSON format. JSON-RPC requires you to conform to their specifications.

APIs that ignore the realities of distributed computing and that each have different special-snowflake wire formats requiring tedious documentation: the worst of both worlds.

Re: When REST isn't Good Enough

#29

Post by pixie_ » Tue, Nov 20, 2012, 6:32 PM UTC

enjo wrote: post #13

pixie_ wrote: post #5

I don't like REST. Making a call to a server should be like calling a function anywhere else - you have your parameters and return value. In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves. It's a much better design to combine all your parameters in one place and keep things simple, for example - REST version: UPDATE /course/324234 { description: "This is a level 1…

The REST version makes it clear that you are dealing with operations on a resource. The URL identifies a thing in a consistent way, while the method and corresponding data allow you to manipulate it. The biggest benefit comes when building a cache architecture. RESTful API's (when properly implemented) come with built-in assumptions about idempotency. You end up in a place where you can easily cache GET requests whil…

Just because something is GET doesn't mean it can be cached. It's not consistent, and every API call needs to be evaluated individually. The thing with REST is that it treats all functions as a variant of a CRUD operation, while functions may do more than just CRUD or a combination of CRUD operations in a single API call. Imagine if all your javascript functions had to be prefixed with GET/UPDATE/DELETE/etc.. you would feel constricted, and for what reason? Imagine if your function names had data in the call path MyCourse.32423.Delete(); that doesn't look very good does it? 32423 would look alot better inside Delete().

Re: When REST isn't Good Enough

#30

Post by mikeknoop » Tue, Nov 20, 2012, 6:32 PM UTC

jeremyjh wrote: post #19

mikeknoop wrote: post #16

We (Zapier) are in a particularly good place to comment on this. We have implemented about 70 very diverse web APIs in-house. Early on, we used client libraries because they were easy and convenient. That decision bit us, hard. (Most) client libraries are un-maintained, opaque, and difficult to extend. We spent many months ripping every client library out down to the raw requests. We are in a unique position because…

Can you respond directly to some of the points raised in the article? For example, ensuring SSL certs are validated?

Sure. I'll start with this: as far as client libraries go, Braintree is doing it right. Because it's the only thing they support, they are incentivized to make sure it is feature complete and bug free.

SSL: It is not the onus of the vendor to ensure people are properly securing requests. I have seen horrendous things done in the name of "security" but it only adds headaches. Fix this at the client level. SSL everywhere is sufficient. By extension, vendors often introduce mechanics because they want to make the world better: http://xkcd.com/927/

Platform Support: I think the counter-argument is community client libraries, which the OP is correct: they are worse. The stability + scaling + support issues mentioned by OP can usually be solved by better API design and better architecture behind the scene.

Backwards Compatibility: OP claims you never have to update your code if you use their client library. This is likely true. Good API design would dictate not breaking exposed endpoints unless there is new functionality to be had. In this case, to take advantage of any new API features, you'd still have to update your code. No cost savings are had either way.