Api

Configuration

Full configuration example:

export default {
  we: {
    api: {
      baseUrl: process.env.BASE_URL,
      apiSuffix: '/api/v1'
      endpoints: [
        'https://api.test.com',
        'https://staging.api.test.com'
      ],
      cache: {
        ttl: 60 * 60 * 1000, // 1 hour
        max: 10,
      }
    },
  }
}

Options

• baseUrl
  • Type: String
  • Initial base url (this will be persisted in localStorage)
• apiSuffix
  • Type: String
  • Suffix of api (the full url will be baseUrl + apiSuffix)
• endpoints
  • Type: Array<String>
  • List of endpoints that will be used to switch between them
• cache
  • Type: Object
  • ttl: Time to live of the cache in milliseconds
  • max: Max number of items in the cache
  • for more options see ttlcache

Endpoint switcher

You can use we-endpoint-switcher to change the endpoint of the app/webapp as follow:

  <we-endpoint-switcher>
    <template #activator="{ attrs, on }">
      <span v-bind="attrs" v-on="on">Easter Egg</span>
    </template>
  </we-endpoint-switcher>

After 5 clicks on the activator, the component will pop up, asking for a password and showing the list of endpoints.

Password

The default password is letmein You change it using the password prop on the component <we-endpoint-switcher password="whatever"/>

WARNING

When a user change the endpoint, this change will be persisted in localStorage

Methods

Every method has a $ prefixed version that returns only the data object of the response.

$request(config)

• Returns Promise

const method = this.id ? 'post' : 'put'
const url = this.id ? 'users' : `users/${this.id}`

// unwrap the data object
const user = await this.$api.$request({ method, url, data: this.user })

// or get the full response object
const { data: user } = await this.$api.request({ method, url, data: this.user })

$get(url, config)

• Returns Promise

const params = {with: 'posts'}
// unwrap the data object
const users = await this.$api.$get('users', { params })

// or get the full response object
const { data: users, meta } = await this.$api.get('users', { params })

$post(url, data, config)

• Returns Promise

const data = { first_name: "John", last_name: "Snow" }

// unwrap the data object
const john = await this.$api.$post('users', data)
// or get the full response object
const { data: john } = await this.$api.post('users', data)

$put(url, data, config)

• Returns Promise

const { user_id } = this.$route.params
const data = { first_name: "John", last_name: "Snow", location: "Winterfell" }

// unwrap the data object
const john = await this.$api.$put(`users/${user_id}`, data)
// or get the full response object
const {data: john} = await this.$api.put(`users/${user_id}`, data)

$patch(url, data, config)

• Returns Promise

const { user_id } = this.$route.params
const data = { location: "Winterfell" }

// unwrap the data object
const john = await this.$api.$patch(`users/${user_id}`, data)
// or get the full response object
const {data: john} = await this.$api.patch(`users/${user_id}`, data)

$delete(url, ...args)

• Returns Promise

const { user_id } = this.$route.params

// unwrap the data object
const deleted = await this.$api.$delete(`users/${user_id}`)
// or get the full response object
const {data: deleted} = await this.$api.delete(`users/${user_id}`)

INFO

Those methods are just a wrapper around axios for an extend configuration check the axios documentation

INFO

To avoid notifications on error, you can pass notify: false in the config object

$getLazy(url, config)

• Returns Promise
• Will cache the response according to the cache option

// same as $get but will cache the response
const users = await this.$api.$getLazy('users')

$getLazyInvalidate(key)

• Will invalidate the cache for the given key

const users = await this.$api.$getLazy(`local_units/${id}/users`)

this.api.$getLazyInvalidate(`local_units/${id}/users`) // invalidate the cache
this.api.$getLazyInvalidate(`local_units`) // invalidate the cache
this.api.$getLazyInvalidate(`users`) // invalidate the cache

buildFormData(url, options)

• Return Promise
• Will transform the data to FormData and return the FormData object
• This method is used internally by $postForm and $putForm
• For more configuration check the object-to-formdata

const data = { 
  name: "John Snow",
  avatar: File,
  age: 25, 
  hobbies: ['ski', 'surf'],
  address: { street: 'Winterfell', city: 'Winterfell', country: 'Westeros' }
  married: false
}
const formData = await this.$api.$buildFormData(data, options)

// {
//   name: "John Snow",
//   avatar: File,
//   age: 25,
//   hobbies[0]: 'ski'
//   hobbies[1]: 'surf'
//   address[street]: 'Winterfell'
//   address[city]: 'Winterfell'
//   address[country]: 'Westeros'
//   married: 0
// }

$postForm(url, data, config)

• Return Promise
• will transform the data to FormData
• Available also postForm

const data = { first_name: "John", last_name: "Snow" }
const users = await this.$api.$postForm(`local_units/${id}/users`, data)

$putForm(url, data, config)

• Return Promise
• will use $postForm with _method: 'PUT'

const data = { first_name: "John", last_name: "Snow" }
const users = await this.$api.$putForm(`/users/${id}`, data)

$patchForm(url, data, config)

• Return Promise
• will use $postForm with _method: 'PATCH'

const data = { first_name: "John", last_name: "Snow" }
const users = await this.$api.$postForm(`/users/${id}`, data)

$download(url, filename, ...args)

• Returns Promise

// simple GET
await this.$api.download('https://api.dev/pics/6')

// define filename
await this.$api.download('https://api.dev/pics/6', 'cool-pic.png')

// define method or other params
await this.$api.download('https://api.dev/pics/6', 'cool-pic.png', { method: 'POST' })

getSignedURL(file, config)

Used to get the signed url from the api server so we can upload the file on the storage directly from the client

• returns Promise

const onFileSelected = (file) => {
  const {key, uuid, url} = await this.$api.getSignedURL(file)

  // key "tmp/774a6d2b-b4c7-4fff-ac44-3a96e34ca106"
  // url "https://bucket.s3.eu-west-3.amazonaws.com/tmp774a6d2b-b4c7-4fff-ac44-3a96e34ca106
  // uuid "774a6d2b-b4c7-4fff-ac44-3a96e34ca106"
}

uploadFile(file, config)

Used to upload the file on the storage directly from the client (using the signed url)

const onFileSelected = (file) => {
  const { 
    key,
    uuid,
    name,
    size,
    mime_type
  } = await this.$api.uploadFile(file)

  // key "tmp/774a6d2b-b4c7-4fff-ac44-3a96e34ca106"
  // uuid "774a6d2b-b4c7-4fff-ac44-3a96e34ca106"
  // name "file_name.pdf"
  // size 123456
  // mime_type "application/pdf"
}

changeBaseUrl(baseUrl)

Used to change the base url of the api

const onEndpointSelected = (endpoint) => {
  this.$api.changeBaseUrl(endpoint)
}

WARNING

When a user change the endpoint, this change will be persisted in localStorage

Vuex getters

baseUrl

• Returns the current base url

this.$store.getters['we:api/baseUrl']

apiUrl

• Returns the current api url (baseUrl + apiSuffix)

this.$store.getters['we:api/apiUrl']