Vuex ORM Axios

# Usage

Vuex ORM Axios adds an asynchronous method api() to all models which, when called, instantiates a new axios request for a model. From these requests, models are able to persist data to the store automatically.

For example, a User model may typically want to fetch all users and persist the response to the store. Vuex ORM Axios can achieve this by performing a simple request:

await User.api().get('https://example.com/api/users')

# Performing Requests

Vuex ORM Axios supports the most commonly used axios request methods (opens new window). These methods accept the same argument signature as their axios counterparts with the exception that the config can be expanded with additional plugin options.

# Supported Methods

Here is a list of supported request methods:

User.api().get(url, config)
User.api().post(url, data, config)
User.api().put(url, data, config)
User.api().patch(url, data, config)
User.api().delete(url, config)
User.api().request(config)

Arguments given are passed on to the corresponding axios request method.

# Request Configuration

You can pass any of the plugin's options together with any axios request options for a request method.

For example, let's configure the following get request:

User.api().get('/api/users', {
  baseURL: 'https://example.com/',
  dataKey: 'result'
})

The baseURL (opens new window) is an axios request option which will be prepended to the request URL (unless the URL is absolute).

The dataKey is a plugin option which informs the plugin of the resource key your elements may be nested under in the response body.

Please refer to the list of supported request methods above to determine where the config argument can be given in the corresponding request method.

See also: Configurations

# Persisting Response Data

By default, the response data from a request is automatically saved to the store corresponding to the model the request is made on.

For example, let's perform a basic get request on a User model:

User.api().get('https://example.com/api/users')

The response body of the request may look like the following:

[
  {
    "id": 1,
    "name": "John Doe",
    "age": 24
  },
  {
    "id": 2,
    "name": "Jane Doe",
    "age": 21
  }
]

Vuex ORM Axios will automatically save this data to the store, and the users entity in the store may now look like the following:

{
  users: {
    data: {
      1: { id: 1, name: 'John Doe', age: 24 },
      2: { id: 2, name: 'Jane Doe', age: 21 }
    }
  }
}

Under the hood, the plugin will persist data to the store by determining which records require inserting and which require updating. To accomplish this, the plugin passes data to the Vuex ORM insertOrUpdate model method. Therefore, only valid model attributes will be persisted to the store.

If you do not want to persist response data automatically, you can defer persistence by configuring the request with the { save: false } option.

As of 0.9.3+ you may configure Vuex ORM Axios to persist data using an alternative Vuex ORM persist method other than the default insertOrUpdate. For example, you can refresh entities by passing the persistBy option as 'create' which will persist data using the model's create method:

User.api().get('/api/users', { persistBy: 'create' })

In addition, you can control how relations are persisted by passing the persistOptions option. Learn more about Insert Method for Relationships (opens new window) in the Vuex ORM documentation.

User.api().get('/api/users', {
  persistOptions: {
    insert: ['posts']
  }
})

See also:

# Delete Requests

WARNING

When performing a delete request, the plugin will not remove the corresponding entities from the store. It is not always possible to determine which record is to be deleted and often HTTP DELETE requests are performed on a resource URL.

If you want to delete a record from the store after performing a delete request, you must pass the delete option.

User.api().delete('/api/users/1', {
  delete: 1
})

See also: Configurations - delete

# Handling Responses

Every request performed will return a Response object as the resolved value. This object is responsible for carrying and handling the response body and ultimately executing actions such as persisting data to the store.

The Response object contains two noteworthy properties:

You may access these properties through the returned value:

const result = await User.api().get('/api/users')

// Retrieving the response status.
result.response.status // 200

// Entities persisted to the store from the response body.
result.entities // { users: [{ ... }] }

See also: API Reference - Response

# Transforming Data

You can configure the plugin to perform transformation on the response data, using the dataTransformer configuration option, before it is persisted to the store.

For example, your API response may conform to the JSON:API (opens new window) specification but may not match the schema for your User model. In such cases you may want to reformat the response data in a manner in which Vuex ORM can normalize.

The dataTransformer method can also be used to hook into response data before it is persisted to the store, allowing you to access other response properties such as response headers, as well as manipulate the data as you see fit.

To demonstrate how you may use this option, let's assume your response body looks like this:

{
  ok: true,
  record: {
    id: 1,
    name: 'John Doe'
  }
}

The following example intercepts the response using a dataTransformer method to extract the data to be persisted from the nested property.

User.api().get('/api/users', {
  dataTransformer: (response) => {
    return response.data.record
  }
})

See also: Configurations - dataTransformer

# Deferring Persistence

By default, the response data from a request is automatically saved to the store but this may not always be desired.

To prevent persisting data to the store, define and set the save option to false. The Response object conveniently provides save() method which allows you to persist the data at any time.

For example, you might want to check if the response contains any errors:

// Prevent persisting response data to the store.
const result = await User.api().get('/api/users', {
  save: false
})

// Throw an error.
if (result.response.data.error) {
  throw new Error('Something is wrong.')
}

// Otherwise continue to persist to the store.
result.save()

When deferring persistence you can also determine whether the response data has been persisted to the store using the convenient isSaved property:

const result = await User.api().get('/api/users', {
  save: false
})

result.isSaved // false

await result.save()

result.isSaved // true

See also:

← Configurations →