Hacker News new | ask | show | jobs
by davetron5000 4954 days ago
This 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.
1 comments
arethuza 4954 days ago
"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.

link
e28eta 4954 days ago
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 representation and passed back into the business logic.

Contrast that with a client library which can do all of that for you, for example: taking a native model object and calling one of two callback functions provided, letting you concentrate on the business logic of your app.

I'm not arguing that a client library is the right way to go, but I certainly understand where the grandparent is coming from RE: boilerplate code. Also, this is going to be heavily influenced by the language and libraries you're using.

link
MatthewPhillips 4954 days ago
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?
link