When REST isn't Good Enough
braintreepayments.com
When REST isn't Good Enough
1–10 of 94 posts
Re: When REST isn't Good Enough
#2This has been my approach to internal service design as well. It's far easier to make sure people integrate properly by providing a rich, well-documented API client library than it is to rely solely on the REST-based one. REST APIs are hard to document, and require a lot of orthogonal boilerplate to even make the requests properly.
Making a client library is also a great way to "dogfood" your REST API - you know a developer will write code, not HTTP calls, to interact with your service. The client API allows you to test out that code and make sure your API is well designed.
Re: When REST isn't Good Enough
#3There are several good points in the article. Particular the one about https.
That said as a clojure dev I'd much rather work with a nice clojure http library like clj-http than have to use their provided java library.
Re: When REST isn't Good Enough
#4Braintree have made an interesting choice in keeping their REST API private and requiring customers use their client libraries. I think they could both have client libraries that they promote as well as a public REST API. Breaking down their reasons:
Security - agree with them on this, the more they can help their users make their systems secure the better. Not sure if it should preclude a public REST API but certainly motivates for having a good client library.
Platform Support - another good reason to have the client library, essentially encoding best practice in the client. I've certainly seen customers abuse features of our APIs. Again, not sure if it should mean keeping the REST API private. Certainly it's a good idea to be defensive on both the client and server (e.g. for queries that request too much data, rate limiting etc.).
Backwards compatibility - Here I disagree with Braintree. I think it should be just as easy to manage backwards compatibility purely on the server side.
Re: When REST isn't Good Enough
#5I 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 course" }
Improved version: POST /course/UpdateDescription { courseId: 324234, description: "This is a level 2 course" }
In this case POST is always used for api calls. Course is the namespace, UpdateDesciption is the method name, and parameters are kept all together as JSON.
Re: When REST isn't Good Enough
#6I 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…
Here's where I've found REST very useful:
It makes for predictable APIs for consumers and it means API producers have a checklist of things to implement to consider their interface 'complete'. It also provides a consistent way to think about how to expose an interface (or in fact, how to expose entities).
Re: When REST isn't Good Enough
#7I 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…
If your course has 20 member variables, now you have 20 update methods? If you want to update multiple, the client then needs to do multiple round-trip calls to your API which is time-consuming: if it's a 350ms round-trip per call, updating all 20 fields takes 7 seconds. And unless you go out of your way to offer per-object locking (which over a stateless connection has its own challenges) you prevent users from doing atomic updates to multiple fields at once. This pushes any rollback mechanism onto the client, exactly where it should not be.
With your design, if your goal is to "combine all the parameters in one place to keep things simple", you could go one step further and have:
POST /course/update {courseId: 1234, field: "description", description: "hello"}
Taking this to its logical extreme, you can truly combine all the parameters in one place:
POST / {object: "course", operation: "update", courseId: 1234, field: "description", description: "hello"}
Re: When REST isn't Good Enough
#8I 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…
REST makes useful to be able to do:
- UPDATE/course/324234 - GET /course/324234 - DELETE /course/324234
with predictable results.
Of course, it works better when you have a clear hierarchy of resources, and/or it make sense to do UPDATE/GET/DELETE to the resources with clear results.
I think it works for some cases very well, but I don't think is always the way to go. That said, there are a sensible number of "RESTful APIs" that are not RESTful at all, they just uses HTTP.
Re: When REST isn't Good Enough
#9I 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 have your parameters and return value.
What you've described is RPC, which has been around for ages. Why do you think REST became a popular alternative to RPC?
Re: When REST isn't Good Enough
#10Note 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 what's there undocumented. It's an interesting approach, but not without its drawbacks.