@vkhalikov/rest-api-client

REST API Client

A basic, extendable client for your REST API.

Installation

npm install --save @vkhalikov/rest-api-client

Basic usage

// resources/todos.js
import { Resource } from '@vkhalikov/rest-api-client';

export const todos = new Resource('todos');

// api.js
import Client from '@vkhalikov/rest-api-client';
import { todos, posts, users } from './resources';

const API_URL = 'https://api.mysite.com';

const resources = [todos, posts];

const api = new Client(API_URL, { resources });

api.route('rest/v2', { resources: [users] });

export default api;

// app.js
import api from './api.js';

let todos;

// final url: "https://api.mysite.com/todos"
api.todos.getAll()
  .then((data) => {
    todos = data;
  })
  .catch((err) => {
    handleError(err);
  });

// You don't have to worry about serialization
// Request body will be automatically serialized with JSON.parse(),
// if 'Content-Type' header contains 'json', which is a default header
const newPost = {
  title: 'Amazing Post',
  message: 'Hello, Worm!',
};

// final url: "https://api.mysite.com/posts"
api.posts.create({ body: newPost });

// final url: "https://api.mysite.com/rest/v2/users/001"
api.users.getById(001);

let adminPosts;

// final url: "https://api.mysite.com/posts/?userId=001"
api.posts.get({ query: { userId: 001 } })
  .then((data) => adminPosts = data)
  .catch((err) => {
    handleError(err);
  });

// You can also make requests directly
api.post('posts', { body: newPost });

API

Client

constructor(baseURL, { resources, authToken, defaultFetchOptions, bodyParser, onError }): Client

Arguments

Argument	Required	Type	Default Value	Description
baseURL		string	undefined	URL of your API.
resources		[Resource]	[]	An array of Resources. Each resource becomes an Client instance property. Example: Resource with name "todos" will be available as api.todos property.
authToken		AuthToken	undefined	An instance of AuthToken. For more detailed information see AuthToken
defaultFetchOptions		object	{ 'Content-Type': 'application/json' }	Will be added to fetch options with every request.
bodyParser		string or function(body: Body, requestMethod:string): Promise	(body) => body.json()	A function that will return a parsed body depending on a requestMethod. If a string is passed, one of predefined body parsers will be used. Valid string options: json, arrayBuffer, blob, text, formData.
onError		function(error): void	undefined	A function that will handle response errors if Response.ok === false. Pass it if you want to specify your own error types depending on response statuses or another information that your API provides, or maybe you want to handle them in one place.

---

Methods

A basic methods, which are you used to create requests with according HTTP methods. You can use them for a specific calls to your API, or if you don't need any Resources.

get(path, options): Promise

post(path, options): Promise

patch(path, options): Promise

put(path, options): Promise

delete(path, options): Promise

Arguments

Argument	Required	Type	Default Value	Description
path		string	undefined	A path to a resource. The result URL will be {baseURL}/{path}?{query}.
options.query		string or object	undefined	Passing this option will result in adding the query part to the final URL. If string it will be passed as is. If object it will be stringified using query-string.
options: {...rest}			{}	Rest options are considered fetch() options.

---

route(path: String, options): void

Arguments

Argument	Required	Type	Default Value	Description
path		string	undefined	A path to a group of resources. All resources passed to this route will be sending requests to a specified path.
resources		[Resource]	[]	Same as for Client

---

setAuthToken(authToken: AuthToken): void

Arguments

Argument	Required	Type	Default Value	Description
authToken		AuthToken	undefined	An instance of AuthToken. Will be passed in Authorization header with every request.

---

resetAuthToken(): void

Sets authToken to null

---

injectResources(resources: [Resource]): void

Manual resource injection.

Arguments

Argument	Required	Type	Default Value	Description
resources		[Resource]	undefined	An array of Resources. Each resource becomes an Client instance property. Example: Resource with name "todos" will be available as api.todos property.

---

Resource

constructor(name, { defaultFetchOptions, bodyParser }): Resource

Argument	Required	Type	Default Value	Description
name		string	undefined	A name of Resource. This defines a name by which a Resource will be available after injection. A name also becomes a path for every request.
defaultFetchOptions		object	undefined	Same as Client.defaultFetchOptions and will be merged with them but takes precedence.
bodyParser		string or function(requestMethod:string, body: Body): Promise	undefined	Same as Client.bodyParser. If passed, will be used instead of Client.bodyParser for this Resource.
path		string	undefined	A path to a resource. Overwrites the default path resolution behaviour (by a resource name).

---

Methods

get({ id, query, ...fetchOptions }): Promise

getById(id, { query, ...fetchOptions }): Promise

getAll({ query, ...fetchOptions }): Promise

create({ body, ...fetchOptions }): Promise

update({ id, query, body, ...fetchOptions }): Promise

replace({ id, query, body, ...fetchOptions }): Promise

delete({ id, query, ...fetchOptions }): Promise

Arguments

Argument	Required	Type	Default Value	Description
id		string	undefined	An ID of a requested resource. Will be added to a final URL: {baseURL}/{resourceName}/{id}.
query		string or object	undefined	Same as for Client requests.
body		any valid body type	undefined	A request body. Examples: string, formData, blob, etc.
fetchOptions		object	undefined	Same as Resource.defaultFetchOptions and will be merged with them but takes precedence.

---

AuthToken

Used in Client. Will be passed in Authorization header with every request.

Example: AuthToken with authScheme Basic and body Base64EncodedToken will become Authorization: Basic Base64EncodedToken header.

constructor(body, { authScheme }): AuthToken

Arguments

Argument	Required	Type	Default Value	Description
body		string	undefined	A token body. Usually base64 encoded.
authScheme		string	Basic	An auth scheme. For more detalied information see IANA list of authentication schemes.

---