@guillaumejasmin/axios-rest

Axios REST

Build resources and actions for axios

• Resources

• Actions

• createAxiosRest()

• Examples

  • Basic config
  • Basic usage
  • URL params
  • Axios request config (params, headers...)

Install

npm install axios-rest --save

What is a resource ?

A resource is a REST endpoint, with a list of actions.

Globals resource actions

Globals resource actions are actions available for all resources.

The most common resource actions are CRUD methods: fetch, create, update and delete.

Example of posts resource:

method	URL	description	Axios Rest
GET	/posts	fetch all post	api.posts().fetch()
GET	/posts/1	fetch one post	api.posts(1).fetch()
POST	/posts	create post	api.posts().create({ data: { title: 'foo' } })
PATCH / PUT	/posts/1	update post	api.posts().update({ { data: id: 1, title: 'bar' } })
DELETE	/posts/1	delete post	api.posts(1).delete()

Custom actions

A resource can also have custom actions only available for this resource:

method	URL	description
POST	/comments/1/like	add a like to the comment 1	api.comments(1).like()
POST	/comments/1/unlike	remove a like to the comment 1	api.comments(1).unlike()

A resource can have sub resources

method	URL	description	Axios Rest
GET	/posts/1/comments	fetch all comment of post 1	api.posts(1).comments().fetch()
POST	/posts/1/comments	create a comment of post 1	api.posts(1).comments().create({ data: { text: '...' } })

What is an action ?

An action is a single endpoint. The most common action is login

method	URL	description	Axios Rest
POST	/login	login to admin panel	api.login({ data: { username: '...', password: '...' } })
POST	/logout	logout from admin panel	api.logout()

createAxiosRest(axiosInst, config)

createAxiosRest(axiosInst, config)

• axiosInst - Axios Instance - required - create with axios.create() . See Axios documentation

• config - object - required

Config

{
  idKey: 'id',
  resources: undefined,
  actions: undefined,
  globalResourceActions: undefined // Actions available for all resources
}

Config resources

{
  [resourceName]: {
    url: '',
    resources: undefined // sub resources
    actions: undefined
  }
}

Config actions

{
  [actionName]: {
    // axios request config
  }
}

// or if you need to get resource id
{
  [actionName]: (id, data) => ({
    // axios request config
  })
}

Examples

Basic config

import axios from 'axios'
import { createAxiosRest, CRUDActions } from 'axios-rest'

const axiosInst = axios.create({
  baseURL: 'http://api.website.com',
})

const config = {
  globalResourceActions: CRUDActions, // use can use predefined CRUD action or build yours
  resources: {
    posts: {
      url: '/posts',
      resources: {
        comments: {
          url: '/comments',
        },
      },
    },
    comments: {
      url: '/comments',
      actions: {
        like: id => ({
          url: `/${id}/like`,
          method: 'POST',
        }),
        unlike: id => ({
          url: `/${id}/unlike`,
          method: 'POST',
        }),
      },
    },
  },
  actions: {
    login: {
      url: '/login',
      method: 'POST',
    },
    logout: {
      url: '/logout',
      method: 'POST',
    },
  },
}

const api = createAxiosRest(axiosInst, config)

Basic usage

Resources

// GET /posts
api
  .posts()
  .fetch()
  .then(res => console.log(res.data))

// GET /posts/1
api.posts(1).fetch()

// POST /posts
api.posts().create({ data: { title: '...' } })

// PATCH /posts/1
api.posts().update({ data: { id: 1, title: '...' } })
// or
api.posts(1).update({ data: { title: '...' } })

// PUT /posts/1
api.posts().update({ data: { id: 1, title: '...' }, method: 'put' })

// DELETE /posts/1
api.posts(1).delete()

Actions

api.login({ data: { email: '...', password: '...' } }).then(res => {
  // success login
})

Sub resources and actions

// GET /posts/1/comments
api
  .posts(1)
  .comments()
  .fetch()

// POST /posts/1/comments
api
  .posts(1)
  .comments()
  .create({ data: { author: '...', text: 'Amazing article !' } })

// POST /comments/1/like
api.comments(1).like()

URL params

const config = {
  actions: {
    myAction: (id, data) => ({
      url: `custom-action/${data.postId}/${data.commentId}`,
    }),
  },
}

// ...

api.myAction({ data: { postId: '', commentId: '' } })

• Note: id is unused here, because it's an action. Id can only be used with resource: api.posts(id).anotherAction()

Axios request config

You have 2 ways to set axios config for an action:

• globally
• during the action call (override global config with shallow merge)

const config = {
  actions: {
    myAction: {
      url: 'custom-action',
      method: 'GET',
      headers: {
        X_CUSTOM_HEADER: 'foo',
      },
      params: {
        page: 1,
      },
    },
  },
}

// ...

// GET /custom-action&page=1
// with header X_CUSTOM_HEADER
api.myAction()

// GET /custom-action&page=2&lang=en
// with header X_CUSTOM_HEADER
api.myAction({ params: { page: 2, lang: 'en' } })