Mercury Api

Overview

This package provides a Mercury Api origin.

• Mercury queries based on query strings and url parameters.
• Built-in cache. Different caches are provided for different queryStrings and url parameters.
• Reactivity to CRUD actions. When a "create", "update" or "delete" method is called over an instance, the instance cache is cleaned.

Api

import { Api } from "@xbyorange/mercury-api"

new Api(url, options)

• Arguments
  • url - <String>. Api url. Parameters can be defined using ":parameterName". Please refer to the path-to-regexp package for further info.
  • options - <Object> Containing options:
    • tags - <String or Array of Strings> - The api instance is added to correspondant groups using these tags. Afterwards, configuration, headers, etc. can be changed for certain groups using the sources object methods described in the mercury docs, or the api object methods described below. The "api" tag is added automatically to all Api instances.
    • baseUrl - <String> - Added as prefix to all requests.
    • createMethod - <String> - HTTP method to be used in axios requests for create method.
    • readMethod - <String> - HTTP method to be used in axios requests for read method.
    • updateMethod - <String> - HTTP method to be used in axios requests for update method.
    • deleteMethod - <String> - HTTP method to be used in axios requests for delete method.
    • authErrorStatus - <Number> - Status code that will be considered as an authentication error. When detected, the authErrorHandler function will be executed instead of returning an error. See the authentication example below.
    • authErrorHandler - <Function> - Handler that will be executed when an authentication error is received.
      • Arguments:
        • origin - origin instance As first argument, the function will receive the origin itself. This will allow to set custom authentication headers after executing login, as example.
        • retry - _<Function> As second argument, a retry function is received, it has to be executed in order to retry the authentication failed request.
      • Returns: This function should return a Promise rejected with an error, or the execution of the received retry method.
    • onBeforeRequest - <Function> - Handler that will be executed before any source method. Useful, for example, to set origin headers just before each request is executed.
      • Arguments:
        • origin - origin instance As first argument, the function will receive the origin itself.
    • onceBeforeRequest - <Function> - Handler that will be executed once time just before the first request. Useful to set origin configuration, for example.
      • Arguments:
        • origin - origin instance As first argument, the function will receive the origin itself.
    • expirationTime - <Number> - The cache will be automatically cleaned each expirationTime miliseconds.
    • retries - <Number> - Number of retries that will be executed when a request fails before definitively failing. Requests will be retried for network errors or a 5xx error on an idempotent request (GET, PUT, DELETE).
    • cache - <Boolean> - Defines whether the resource will use cache or not. If false, all "read" executions will be sent to the server.
    • fullResponse - <Boolean> - If true, the full response object will be used as value, so you can consult headers, etc. If false, only the response.data will be returned, which is the default behavior.
    • validateStatus - <Function> - Function that will be used to determine if response status has to be considered as failed or success.
      • Arguments:
        • status - <Number> - Status code of the request.
      • Returns: Should return true for success requests, and false for failed ones.
    • validateResponse - <Function> - Function that will be used to determine if response has to be considered as failed or success.
      • Arguments:
        • response - <Object> - Response of the request.
      • Returns: Should return a Promise resolves for success requests, and a Promise rejected with an error for failed ones.
    • errorHandler - <Function> - Function used to parse errors. The returned value will be setted as error in the origin error property.
      • Arguments:
        • error - <Error> - Error object produced by a failed request.
      • Returns: Should return a rejected Promise, containing the new Error.
    • defaultValue - <Any> - Default value of origin until real data is requested.

Methods

query

api.query(queryObject)

• Arguments
  • queryObject - <Object> containing properties:
    • queryString - <Object> Keys of the object will be passed as query strings in the url of the request.
    • urlParams - <Object> Keys of the object will be replaced by correspondant url parameters defined in the url as ":param". Please refer to the path-to-regexp package for further info.
• Returns - New queried api instance having all methods described in this chapter.

clean cache

api.clean()

• The cache of a queried api resource will be automatically cleaned when the update or delete methods are executed for that query.
• If update or delete methods are executed over the origin without query, cache of all queried resources will be cleaned too.
• All cache will be cleaned if the create method is executed.

setHeaders

Define headers that will be applied to all subsequent requests.

api.setHeaders(headers)

• Arguments
  • headers - <Object> Each property in the object will be applied as a header.

booksCollection.setHeaders({
  Authorization: `Bearer ${token}`
});

addHeaders

Add a new header. Current headers will be extended with received headers object, and applied to all subsequent requests:

api.addHeaders(headers)

• Arguments
  • headers - <Object> Each property in the object will be applied as a header.

booksCollection.addHeaders({
  "Cache-Control": "no-cache"
});

config

Config method can be invoked at any time to change the configuration. The resultant configuration will be the extension of the current options with the provided ones.

api.config(options)

• Arguments
  • options - <Object> Options object as described above.

Handling many api instances at a time.

apis object methods allow to set headers of many instances at a time. Apis can be grouped and categorized using tags (through the tags option), and this methods will be applied only to apis matching provided tags.

If no tags are provided when invoking methods, they will be applied to all api instances.

An example of multiple configuration is available in the docs.

import { apis } from "@xbyorange/mercury-api"

clean cache

Use the "mercury" sources method for cleaning many instances at a time. Use the "api" tag to clean all "mercury-api" instances:

import { sources } from "@xbyorange/mercury";

sources.getByTag("api").clean();

setHeaders

It defines headers that will be applied to all subsequent requests of api instances matching provided tags.

apis.setHeaders(headers [,tags])

• Arguments
  • headers - <Object> Headers object to be applied as in api.setHeaders method described above.
  • tags - <String or Array of Strings> Tag/s of those apis in which the setHeaders method should be executed. If no defined, setHeaders method of all api instances will be called.

apis.setHeaders({ Authorization: `Bearer ${token}` }, ["need-auth"]);

addHeaders

It adds a new header to all api instances matching provided tags. Current headers will be extended with received headers object, and applied to all subsequent requests:

apis.addHeaders(headers [,tags])

• Arguments
  • headers - <Object> Each property in the object will be applied as a header.
  • tags - <String or Array of Strings> Tag/s of those apis in which the addHeaders method should be executed. If no defined, addHeaders method of all api instances will be called.

apis.addHeaders({ Authorization: `Bearer ${token}` }, ["need-auth"]);

config

Use the "mercury" sources method for configuring many instances at a time. Use the "api" tag to configure all "mercury-api" instances:

import { sources } from "@xbyorange/mercury";

sources.getByTag("api").config({
  retries: 0
});

Examples

Next example will be easier to understand if you are already familiarized with the mercury syntax.

import { Selector } from "@xbyorange/mercury";
import { Api } from "@xbyorange/mercury-api";

const booksCollection = new Api("http://api.library.com/books");
const authorsCollection = new Api("http://api.library.com/authors");

const booksWithAuthors = new Selector(
  {
    source: booksCollection,
    query: author => {
      queryString: {
        author
      }
    }
  },
  authorsCollection,
  (booksResults, authorsResults) =>
      booksResults.map(book => ({
      ...book,
      authorName: authorsResults.find(author => author.id === book.author)
    }))
);

// Each book now includes an "authorName" property.
const results = await booksWithAuthors.read();

// Request is not dispatched again, now results are cached.
await booksWithAuthors.read();

console.log(booksWithAuthors.read.value); //Value still remain the same

booksCollection.create({
  author: "George Orwell",
  book: "1984"
});

// Request to books is dispatched again, as cache was cleaned. Authors are still cached.
await booksWithAuthors.read();

// Request is dispatched, but passing "author" query string
const booksOfOrwell = await booksWithAuthors.query("George Orwell").read();

// Request is already cached. It will not be repeated.
await booksWithAuthors.query("George Orwell");

More examples

The mercury library uses this origin in his examples, so you can refer to the library documentation to found more examples.

Specific api origin examples:

• configuration
• configuring multiple instance at a time
• authentication

Usage with frameworks

React

Please refer to the react-mercury documentation to see how simple is the data-binding between React Components and mercury-api.

Connect a source to all components that need it. Mercury will fetch data only when needed, and will avoid making it more than once, no matter how many components need the data.

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.