Everest NPM | npm.io

Everest.io

The last REST client you'll ever need. Universal javascript, works both on server and in browser.

Status

Note: This library is under massive development. I've published it to get early feedback.

Quick start

Note: This library requires Promise and fetch in global scope. Use bluebird and isomorphic-fetch polyfills if you don't have them already.

You need very few lines to get started with everest:

    import Everest from "everest";

    // objects returned from Api are bind to Model
    const api = Everest('/document');
    const documents = api.all().then(() => {  // GET /document
      const document = documents[0];
      api.model(document).update({title: "The history of mountaineering"}); // PATCH /document/1
    });

    // objects can be also bind directly
    const document = api.model(1);
    document.get(); // GET /document/1

Everest is a factory, which creates a Collection model with standard operations for /document endpoint:

Collection method	Api call
`.all()`	`GET /document`
`.create(data)`	`POST /document`

Model is bound to specific resource (either by id or url) and have following methods:

Model method	Api call
`.get()`	`GET /document/:id`
`.replace(data)`	`PUT /document/:id`
`.update(data)`	`PATCH /document/:id`
`.remove()`	`DELETE /document/:id`

All methods return promises.

Create your own models

This library uses object composition. There are mixins for all methods: all, get, create and etc. If you don't need any of them or you want to implement your own version, simply compose together mixins you need:

  import Api from "everest/base";
  import {getAll, getOne} from "everest/mixins";

  function DocumentAPI() {
    return Object.assign(
      Object.create(Api()),
      getAll, getOne,
      {
        endpoint: "/document",

        // own method
        publish(data): {
          return (
            this
            .fetch(this.endpoint, {
              method: "post",
              headers: {
                "Accept": "application/json",
                "Content-Type": "application/json"
              },
              body: JSON.stringify(data)
            })
            .then(validateStatus(200))
            .then(parseJSON)
            .catch((error) => {...})
          );
        }
      }
    )
  }

Thanks to object composition, we can combine only those mixins that we really need and that our Api supports.

There's only one class which is inherited using prototype: ApiConfig. So suppose you want to change base URL for all models:

  import Everest, {ApiConfig} from "everest";

  ApiConfig.base = "https://api.everest";

  const api = Everest("/document");
  api.all()  // GET https://api.everest/document

Mocking of requests

Code without tests is broken by design. -- Jacob Kaplan-Moss

Everest is designed with testing in mind. Using mockMixin we can define responses for endpoints. HTTP request to the remote server is never made in this case. Mocking needs to enabled by settings ApiConfig.mocked = true.

  import {ApiConfig} from "everest";
  import {mockMixin, responseMock} from "everest/mock";

  const DocumentList = [...];   // list of document
  const DocumentMock = {...};   // detail of document

  // route: response
  const routes = {
    "document": {
      "get": () => responseMock(DocumentList),
      "post": () => responseMock(DocumentDetail),
    },
    "document/1": () => responseMock(DocumentDetail)
  };

  function Document() {
    return Object.assign(
      Everest("document"),
      mockMixin(routes)
    );
  }

  const api = Document();
  ApiConfig.mocked = true;  // enable mocking
  api.all();  // mocked call

The routes have to be created manually as we did, or (hold your breath) generated automatically from Api Blueprint. This feature is planned. PR welcome.

Reference

Config

All configuration variables can be set either globally using ApiConfig or locally by passing arguments to Everest factory:

   import Everest, {ApiConfig} from "everest";  // or "everest/base"
   ApiConfig.mocked = false; // global configuration

   const Document = Everest("document", {mocked: false}); // local configuration

ApiConfig.base (string, default: "") - Base URL which is prepended to all endpoints
ApiConfig.mocked (boolean, default: false) - Enables/Disables mocking of requests (only has an effect on models which use mockMixin)