# Endpoints

Endpoints are base class objects that uses axios to call endpoints, then results and errors are stored inside them.

# Defining Endpoints

To define an endpoint, just add chimera property to root of your vue component instance, then add your endpoint definitions to chimera object.

Chimera properties will be automatically converted to Endpoint object

export default {
  
  // Chimera property contains all restful endpoints
  chimera: {
    
    // Here you can define your restful endpoints and api endpoints
    products: '/products',

    // a sample POST request
    sendProduct: {
        url: '/products',
        method: 'POST',

        // POST body
        params: {
          title: 'My Product',
          description: 'Vue Chimera is awesome...'
        },
        auto: false
    }

    // endpoint keys cannot start with $ (dollor sign)
  },
  
  data() {
    return { ... }
  }
  
}

Endpoint definition can be anything coompatible with axios configuration format:

  • string: A simple string for simple GET requests
  • Object: For complex endpoints like: POST, PATCH, with Parameters, with Headers
  • Endpoint: An instance of Endpoint (manually instantiate Endpoint)
  • Function: for reactive endpoints Reactive-Endpoints (explained later)

# Endpoint options

Properties Type Default value Description
key String null Unique key that identifies an endpoint, used for caching and server side fetching purpose.
We recommend to always set it on every endpoint
url String Endpoint url
baseURL String Endpoint base url like: http://example.com/api/
method String GET Endpoint method: (POST/GET)
headers Object {} Request headers
params Object {} Request parameters (Query string for GET / Body Data for POST/PATCH/DELETE)
auto Boolean/String 'get' A boolean flag that indicates endpoint should be fetched on instantiation or reactive changes.
If it's a string, fetches endpoints with same request method
transformer Function/Object null Transform response or error results to something else
interval Number undefined A number in miliseconds to auto refresh an api
debounce Number 50 A number in miliseconds that prevent duplicate api calls during this time, can be set to false to disable debouncing.
cache Cache null Cache strategy object. More info
timeout Number 0 Request timeout
axios Axios/Object null Axios instance to send requests
on Object null Sets event listeners Events
prefetch Boolean Equals to auto if not set A boolean flag that indicates endpoint should be fetched on server. More Info
prefetchTimeout Number 4000 A number in milliseconds that indicates how much should wait for server to fetch endpoints

* options is the same axios configuration. Any other axios configuration can also be set.

Note : All the endpoint options can have some defaults, like baseURL or headers. To set global defaults we can use plugin options or set $options on a Chimera instance

# Sending endpoint request

Component endpoints can be accessed via $chimera property injected to vue instance, and also for simplicity if there is no props or data conflicting endpoint name, endpoints can directly accessed via it's name.

export default {
    chimera: {
       posts: '/posts'
    },
    mounted () {
        this.$chimera.posts === this.posts // True
    }
}

Endpoints are automatically loaded on component create if method is GET, but can be overrided with setting auto is set to true or false

export default {
    chimera: {
        users: '/users', // By default GET requests has `auto`
        usersNotAuto: {
           url: '/users',
           auto: false, // Disable auto on GET
        },
        newUser: { // POST/PUT/PATCH/DELETE requests are manual. `auto`: false
           url: '/users/new', 
           method: 'POST',
           params: { name: 'John Doe' }
        },
        newUserAuto: { // But can explicitly set to auto
           url: '/users/new', 
           method: 'POST',
           params: { name: 'John Doe' },
           auto: true,
        }
    },
    method: {
       submit () {
         this.newUser.fetch()  // calling POST request
         this.usersNotAuto.fetch() // fetching
       }
    }
}

Or they can be manually fetched via calling .fetch() or .reload() method on the endpoint instance

# Using endpoints

Endpoints have props and methods that can be used to send requests and extract the results

# Properties

Property Type Initial Value Description
data Object/Array null Endpoint response JSON object returned from server when request is successful.
Might be transformed through transformers
loading Boolean false Indicates the endpoint is in loading state
error Object/Array/String null Error json object or string returned from server when request failed
lastLoaded Date null Date object from last time endpoint successfully loaded (null if not loaded yet)
status number null Endpoint response status
headers Object {} Endpoint response/error headers
---- ---- ---- ----
params Object Parameters passed to endpoint on definition
url String Url passed to endpoint on definition
method String Request method (GET/POST/...) passed to endpoint on definition
looping Boolean Boolean indicates that endpoint is looping (interval option)

# Methods

Method Return type Description
fetch(force, extraOptions) Promise Fetches the endpoint from server.
force: True for cache busting,
extraOptions Merged into current endpoint axios config for extra options & params
reload(force) Promise Same as fetch, (debounced)
send(extraParams) Promise Send request but with extra parameters in body or query string
on(event, handler) Sets an event listener. Events
cancel() void Interupts request
startInterval() void Manually starts interval (auto refresh)
stopInterval() void Manually stops interval

# Using Inside template

  • data is the final json result of our restful endpoint
  • loading is a boolean flag, identifies the endpoint is loading.
  • error is a final json result of error response. You can read other endpoint property and methods here.
<template>
  <div>
    <!-- `users` is Endpoint object (same as: `$chimera.users`) -->
    <ul v-if="users.data && !users.loading">
      <li v-for="user in users.data">
        {{ user.name }}
      </li>
    </ul>
    <small v-else>Loading...</small>
  </div>
</template>

<script>
export default {
    chimera: {
        users: '/users'
    }
}
</script>

# Using Programmatically

export default {
    chimera: {
        users: '/users'
    },
    computed: {
       users () {
           const users = this.$chimera.users.data
           if (!Array.isArray(users)) return []
           return users
       }
    },
    mounted () {
        setTimeout(() => {
            this.$chimera.users.reload() // or users.reload()
        }, 15000)
    },
}

# Auto refresh endpoints

You can use interval property to auto refresh endpoints after time

export default {
    chimera: {
        users: {
           url: '/users',
           interval: 10 * 1000 // 10 seconds
        }
    },
    methods: {
       // Manual start and stop
       stopInterval () {
          this.users.startInterval(10000)
          console.log(this.users.looping) // true
          setTimeout(() => {
             this.users.stopInterval()
             console.log(this.users.looping) // false
          }, 500000)
       }
    }
}
Last Updated: 3/20/2020, 12:15:01 PM