Skip to main content

Getting Started

Learn how to use the @availity/api-axios package for communicating with our APIs

Version

Installation

Install the package through npm, yarn, or your favorite package manager. You must also install axios as well.

NPM

npm install @availity/api-axios axios

Yarn

yarn add @availity/api-axios axios

AvApi

AvApi is the default export from @availity/api-axios. It is a class that wraps axios.

Features

  • Automatic polling of restful endpoints with timeouts
  • Simple URI builder for API resources
  • Life-cycle hooks into HTTP calls for GET, PUT, POST, and DELETE

Usage

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

Options

http

The default http client used is axios. You can pass an object to this parameter in order to override axios.

config

axios config object that will be passed to each call.

Request Config

Listed below are the options we primarily use from the axios config or ones we have added.

config.api

Default true. When true, the url is built out by joining path, version, and name or just url if no name is defined. The id is also added when appropriate. When api is false, all calls just use url. URL pattern: path/version/name

config.url

This is used for requests when config.api is false or name is undefined;

config.path

Used for url building when config.api is true. URL pattern path/version/name

config.version

Default v1. Used for url building when config.api is true. URL pattern path/version/name

config.name

The name of the resource. Used for url building when api is true. (path/version/name)

config.cacheBust

Disable caching for every request by adding a cacheBust parameter to the call.

Accepts a boolean, function, or some value:

  • If true, a timestamp is generated and used
  • If a function, it is called and return value is used
  • If a value is passed then the cache bust param is set to this value.
config.pageBust

Bust the browser cache on page load, and keep its value for lifecycle of the page. Same behavior as cacheBust except if true, a value is only generated once and re-used. A hard refresh of page resets the pageBust value. To manually set the pageBust value call without changing the config, use setPageBust(value) which will set the it to value or if undefined generate a timestamp.

config.sessionBust

Default true. Attempts to read a value in local storage that is generated at login. This forces the browser to bust the cache when a new session has started. If the local storage value is not found, uses the pageBust value.

config.polling

Default true. If true and rest services return 202 statuc code, AvApi will attempt to poll on predefined internvals until the retries are exhausted or the api returns non 202 response.

config.pollingIntervals

An array of intervals (ms) to wait before making another request. Default is 1, 2, 5, then 10 seconds. After all the intervals have been used, AvApi will stop attempting requests and return the last response.

config.getHeader

Used for polling, if the http service used has special logic to get a header value, then define this function to handle that logic. If defined, it is called with (response, headerKey). If not defined, attempts to get key from response.headers[key].

Methods

Each method can use an after function, (ex. afterGet with get). These are available to modify the response before it is resolved. Each method that has data available has a before function in order to modify data before the call is made.

All methods accept a config object, which is merged into the resources config for that call only.

create or post

Makes HTTP POST request.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const post = async (data, config) => {
const response = await api.post(data, config);
return response.data;
};

// OR
const create = async (data, config) => {
const response = await api.create(data, config);
return response.data;
};

postGet

Makes HTTP POST using X-HTTP-Method-Override = 'GET'. There server must support override methods for the request to succeed.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const postGet = async (data, config) => {
const response = await api.postGet(data, config);
return response.data;
};

get

Retrieves an entity by ID. Makes HTTP GET call with /id in url.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const get = async (id, config) => {
const response = await api.get(id, config);
return response.data;
};

query

The query function is designed to fetch collections and search the API. Makes HTTP GET request with query params.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const query = async (config) => {
const response = await api.query(config);
return response.data;
};

update or put

Update an entity with a PUT call. When an id is passed in, /id is added to the url.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const put = async (id, data, config) => {
const response = await api.put(id, data, config);
return response.data;
};

// OR

const update = async (data, config) => {
// You can also omit the id. this works for `put` as well
const response = await api.update(data, config);
return response.data;
};

patch

Update an entity with a PATCH call. When an id is passed in, /id is added to the url.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const patch = async (id, data, config) => {
const response = await api.patch(id, data, config);
// You can also omit id, and only pass in data and config
// const response = await api.patch(data, config);
return response.data;
};

remove or delete

Remove an entity with a DELETE call. When an id is passed in, /id is added to the url. If the first parameter is a string or number, it is treated as an ID, otherwise data.

import AvApi from '@availity/api-axios';

const api = new AvApi({ name: 'test' });

const remove = async (id, config) => {
const response = await api.remove(id, config);
return response.data;
};

// OR

const delete = async (data, config) => {
const response = await api.delete(data, config);
return response.data;
};

AvMicroserviceApi

AvMicroservice extends AvApi and thus can call the same methods. It has slightly different default config options.