Drowsy

A universal REST client that makes integrating with services so wonderfully simple, you'll probably forget you're talking to an API after all. Think gRPC or SOAP, but for REST.

Description

A hugely versatile REST client and server interface, that lets you extend libraries like Request, Express, Axios, Fastify, and many more, largely by removing the need for the boilerplate code often inherent when using these tools.

At its heart, Drowsy builds upon a common design pattern found in the majority of the HTTP related tools that the community has to offer. More often than not, the pattern looks like this.

library.get(url[, options][, cb])

This was likely inspired by the original Node.js HTTP module

Drowsy is able to simplify the above by hoisting both the method and URL into the function name, providing a more gRPCesque interface, and cutting out any hardcoded URL strings.

API.getPing([, cb]);

This is an incredibly powerful abstraction, and one that can be stacked endlessly. This easily leads to even further optimisations, allowing your REST client or server to be treated as though it was nothing more than a large object of functions.

var UsersAPI = API.users

// Call GET hostname/users/all
UsersAPI.getAll([, cb])

// Call POST hostname/users/<userId>
UsersAPI.post[userId](options[, cb])

These function calls are largely identical for the client and server, only when there are placeholders in the URL will the Drowsy syntax differ.

Featured on Changelog

Examples

Below is a super simple example demonstrating how easy it can be to retrieve the first page of public Gists currently available on GitHub.

const github = drowsy(request, "https://api.github.com/");

github.getGists({
  headers: {
    "User-Agent": "Octo-app"
  }
});

By calling the method getGists you're in fact performing a GET request to the endpoint "/gists" through the handler provided (in this case, Request). The handler returns a Promise that will, hopefully, resolve in a timely fashion with the first page of public Gists found on GitHub.

Usage

Single command

The single command approach is the simplest and most human readable of the bunch, it has some minor limitations, but nothing that can't be avoided with a little imagination.

Each request is composed using just one lookup (both the HTTP method and the URL must be known at the time of writing). It's super elegant, and recommended to be used when talking to an API that has collections, or otherwise grouped endpoints exposed.

Limitations

This approach will only work with single word URL parts, and requires that you know all of them too, here's a breakdown of what would and wouldn't work.

// Yes - API.getCitiesLondon()
/cities/london

// Yes - API.getCitiesLondonPopulation()
/cities/london/population

// No - try API.getCities[cityId]()
/cities/[:cityId]

// No - try API.getCitiesLondon["is-capital"]()
/cities/london/is-capital

License

This project is released under the MIT License. Enjoy responsibly ✌️