Consumer
A tiny REST API consumer for JavaScript projects
Installation
npm install --save api-consumer
This project uses modern JavaScript API's, and does not polyfill anything. To use Consumer in older browsers, you will need to provide your own polyfills for fetch
, Promise
and Proxy
as required.
Usage
Consumer uses proxy objects to allow using chainable properties to construct a url for a REST API endpoint, and then execute the request for you. Each property you chain is appended to the url, and returns a new proxy. If you call one of the methods all
, find
, create
, update
, or delete
at any point in the chain, a fetch
request is executed, and the parsed JSON response is returned to you in a Promise.
See below for a brief explanation of functionality, or try out Consumer in the playground on RunKit.
Making Requsests
// Create the proxy with your API's base URLconst api = // GET https://your.domain.com/api/usersconst users = await apiusersall // GET https://your.domain.com/api/your/deeply/nested/endpointconst users = await apiyourdeeplynestedendpointall // GET https://your.domain.com/api/users/123/postsconst posts = await apiusers123postsall // GET https://your.domain.com/api/users/123const user = await apiusers // POST https://your.domain.com/api/usersconst newUser = await apiusers // PUT https://your.domain.com/api/users/123const updatedUser = await apiusers // DELETE https://your.domain.com/api/users/123const deletedUser = await apiusers
Using Models
By default, a request made with a consumer returns a Model
instance, or a Collection
.
const api = // GET https://your.domain.com/api/books// @returns {Promise<Collection[Model]>}const book = await apibooksall123 // GET https://your.domain.com/api/books/123// @returns {Promise<Model>}const book = await apibooksbooktitle = 'A new title' // PUT https://your.domain.com/api/books/123// @returns {Promise<Boolean>}let saved = await book // DELETE https://your.domain.com/api/books/123// @returns {Promise<Boolean>}let deleted = await book
You can extend the model's functionality by creating your own model classes.
const api = // Extend the model class // Specify a Consumer instance to use as an endpoint static consumer = apibooks // Optionally specify a custom primary key field (The default is 'id') // The value of this field is used in the URL for update, create and delete static primaryKeyField = 'uuid' // Override getters and setters { return 'Rainbows!' }
Now you can query your model class directly.
// GET https://your.domain.com/api/booksconst books = await Bookall // GET https://your.domain.com/api/books/123const book = await Bookbooktitle = 'A new title' // PUT https://your.domain.com/api/books/123let saved = await book // DELETE https://your.domain.com/api/books/123let deleted = await book
You can also use the constructor to create new resources.
const book = booktitle = 'A title'bookauthor = 'Joe Bloggs' // POST https://your.domain.com/api/books// @returns {Promise<Boolean>}let created = await book // Creating statically has the same effect// @returns {Promise<Model>}const book = Book
fetch
options
Overiding The default options passed to fetch
are:
credentials: true headers: 'Content-Type': 'application/json'
You can override these by passing an object as the second argument to consume
.
const api =
NOTE: Specifying method
in the default options will have no effect, since it is overridden by each of the executing methods.
License & Contributing
- Details on the license can be found here
- Details on running tests and contributing can be found here