22

I'm looking for best-practise styles for wrapping a REST API in a light-weight JavaScript client.

In the past I've seen libraries which are implemented in a style like:

var request = new SearchRequest(apikey);
request.query = "search term";
request.send(function(results) {
    console.log(results);
});

Or that embrace HTTP more explicitly like:

api.get("search", "search term", function(results) {
    console.log(results);
});
api.post("comment", comment, function(results) {
    console.log(results);
});

Or that wrap at an even higher level:

api.search("search term", function(results) {
    console.log(results);
});
api.createComment(comment, function(results) {
    console.log(results);
});

What good examples of modern JavaScript client libraries wrapping REST APIs have you seen recently. Not worried about implementation details, just the API design.

Thanks!

Andy Hume
  • 40,474
  • 10
  • 47
  • 58
  • 3
    Personally I'm a fan of your third (higher level abstraction) example. It feels more like an SDK and less like a light weight wrapper. – Alex K Jan 23 '15 at 17:53

2 Answers2

10

I watched a really good video on good API Design. Definitely worth the watch.

RESTful API Design - Second Edition

You can also get a free book Web API Design - Crafting Interfaces that Developers Love in addition to the above video by going to https://offers.apigee.com/ebook-api-design-yt/

Regarding wrappers it may be worth thinking about the following:

  1. Make your wrapper consistent.

Adopt the standards, naming conventions, etc of the programming language or community you are working with to make the wrapper feel as natural as possible to those using it.

  1. To wrap or to abstract? That is the question.

By Wrapping you mimic the REST API methods and structure as much as possible but simply make some of the hard things easier. One of the biggest advantages of this approach is that it makes it easier to upgrade when the target REST API upgrades.

Abstracting is useful when the target REST API is complex or behaves and looks in non-standard ways. In this case your wrapper methods and calls may not resemble your target REST API methods at all but will ultimately simplify the life ( hopefully ) of those using your wrapper.

General Grievance
  • 4,555
  • 31
  • 31
  • 45
Bruno
  • 5,772
  • 1
  • 26
  • 43
4

Check these ones:

There are other similar discussions on StackOverflow, like JavaScript REST client Library

Community
  • 1
  • 1
François Zaninotto
  • 7,068
  • 2
  • 35
  • 56
  • Restangular minified version 20kb, but Restful minified version 78kb. Too much for REST, as I think. – Seigiard Nov 10 '15 at 18:23
  • 1
    restful.js depends on immutable.js, which accounts for more than 50kb of the minified restful source. If you already use immutable.js in your application (which is very common for ReactJs/Redux projects), and use webpack to build, immutable.js will be added just once. Therefore the size of restful will be much like Restangular. – François Zaninotto Nov 12 '15 at 08:55
  • 1
    Also, if you use Angular, you should definitely use Restangular. Restful.js is better suited to Applications not using Angular. And in that case, part of the Anguler source (e.g. $http) need to be ported somehow to the restful core. – François Zaninotto Nov 12 '15 at 09:00
  • Backbone.js should be on that list. It has a nice object-oriented rest model. – trusktr Apr 29 '19 at 03:49