Skip to content

Latest commit

 

History

History
220 lines (162 loc) · 10.1 KB

README.md

File metadata and controls

220 lines (162 loc) · 10.1 KB
Raw

Quasar App Extension

API Wrapper

===

An easy to use out of the box API wrapper that use axios in its core

Note: The extension can be used as an npm package, using: api-client-wrapper

This extension was designed to wrap up the most common features of an api client implementation, in an effort to have a quick and stable tool for each project.

The present features in the extension are:

  1. Easy global access: The extension came with a Quasar boot script that put an $api object available at global scope for any Vue component as: this.$api. You can access the $api object from inside any Vue component.

  2. Base API url: The url that will be used as a root for any call that contains a relative path this.$api.baseURL. Note: If a call contains a full path (one with http or https protocol) it will be called as is without baseURL concatenation.

  3. Homogeneous response: Each request is a promise that resolve with an homogeneous response object: {success:Boolean, attempts:int, data:Object, info:string, error:Error}. For more details refer to the Response Schema section on this readme.

  4. Concurrent requests: All the requests could be made simultaneously. By default the limit is configured to 5 concurrent requests, but it could be changed at this.$api.simultaneousCalls

  5. Timeout and retry: In the case of a timeout response a request could be configured to try again with: this.$api.maxAttemptsPerCall the default value is 1. Each attempt will be executed transparently and it will be just one response so the code for a request with a single attempt will be the same as for a request with multiple attempts.

  6. Masive requests: There is out of the box support for bulk calls that allows multiple requests in a single call. for more information refer to the How To use it section on this readme.

  7. Vuex integration: The extension came with Vuex store integration for state monitoring. During Quasar boot phase a module is registered to Vuex with the next information:

    1. Working: Indicating that is at least one request executing this.$store.state.APIwrapper.working
    2. Uploading: Indicating that is at least one request executing with a method different from GET this.$store.state.APIwrapper.uploading
    3. Downloading: Indicating that is at least one request executing with a method equal to GET this.$store.state.APIwrapper.downloading
    4. Request Count: Indicates the amount of requests being managed, executing requests + waiting for execution requests this.$store.state.APIwrapper.request_count
    5. Execute Count: Indicates the amount of requests being executed in a concurrent manner this.$store.state.APIwrapper.executing_count

Note: It is possible to have the store configured out of the boot phase using this.$api.setStore(Vuex_instance). Refer to the How to use it section.

Install

quasar ext add api-wrapper

Quasar CLI will retrieve it from NPM and install the extension.

Uninstall

quasar ext remove api-wrapper

How to use it

Performing a GET request

// Inside any Vue componente
let result = await this.$api.get('path');
//or
this.$api.get('path').then(result=>{});

Performing a POST request

// Inside any Vue componente
let result = await this.$api.post('path', {data});
//or
this.$api.post('path', {data}).then(result=>{});

The supported methods are:

// Inside any Vue componente
this.$api.get(path='', conf = {})
this.$api.post(path='', data = {}, conf = {})
this.$api.patch(path='', data = {}, conf = {})
this.$api.put(path='', data = {}, conf = {})
this.$api.delete(path='', conf = {})

//Or the global method that receive a request Configuration (in most of the cases you will never need this method)
this.$api.call({request configuration})

Note that each method has a final argument that is a custom configuration for the request, this configuration takes precedence over the global configuration. For the supported properties please refer to the Request Configuration section.

Use outside a Vue component

You can use APIWrapper from outside a Vue component, this is common if you want to use it in a store module or inside any other js file Eg. A Quasar bootfile.

// import the object
import api from "api-client-wrapper"

// Use any of the available methods
api.get(path='', conf = {})
api.post(path='', data = {}, conf = {})
api.patch(path='', data = {}, conf = {})
api.put(path='', data = {}, conf = {})
api.delete(path='', conf = {})

Important Note: You are still referencing the same object that you use inside any Vue component, so if you make any configuration it will affect any other place where you were using it, and the same goes in viceversa, any previous configuration made will take effect.

Bulk calls

Each method has a bulk counterpart that allows for bulk calls

// Inside any Vue componente
let result = await this.$api.bulkGet(['paths' or {configs}], continueWithFailure:Boolean, onProgress)
let result = await this.$api.bulkPost(['paths' or {configs}], continueWithFailure:Boolean, onProgress)
let result = await this.$api.bulkPatch(['paths' or {configs}], continueWithFailure:Boolean, onProgress)
let result = await this.$api.bulkPut(['paths' or {configs}], continueWithFailure:Boolean, onProgress)
let result = await this.$api.bulkDelete(['paths' or {configs}], continueWithFailure:Boolean, onProgress)

//or the global method that allows bulk calls with different methods
let result = await this.$api.bulkCall([{configs}], continueWithFailure:Boolean, onProgress)

Params:

  • [paths or configs]:[]-> An array containing the paths for each request or an array of request configuration objects (described next).
  • continueWithFailure:Boolean-> Optional with the default to false. false The request will be considered failed when any of it subrequests fail and it will stop any further execution (there could be some sub-requests that never get executed if some other request failed before). true All the requests are executed, it doesn´t matter if some of them failed.
  • onProgress:Function(progress:Number)-> Is an optional callback that receives progress between [0-1], the progress is computed with the next formula: (request-completed / total-amount-of-request-in-the-bulkCall)

Request Configuration

A configuration object for each request, which have precedence over any global configuration (so it is a way to override any global configuration for special scenarios) It has the next scheme:

{
// Relative or absolute path for the call. Always needed except for when a path was already passed as an argument
url:String,

// The HTTP verb to be used for the request
method:String,

// the URL parameters to be sent with the request
params:{},

// Data to be sent as the request body
data:{},

// An alias to be added to the response of this request for better indentification with bulk calls
alias:String,

// Number of attemps for the request in case of timeout failure
attempts:1,

// Number of milliseconds before the request times out.
timeout:10000

// Any other property supported by axios configuration
...
}

It is possible to add any property supported by axios (like headers or encoding).

Response Scheme

For any individual request the response schema is:

{
// Present only when an alias was passed in the config for the request
alias:String,

// true: when the status of the request is between [200-300) 
// flase: for any status not in the range of 200's
success:Boolean,

// Number of attemps made by this request before being considered completed
attempts:0,

// Any data returned in the response or an array of responses in the case of a bulk call
data:{}

// The error message present when an error is returned with the response
info:"",

// The error instance present in the response (if there is one)
error:null,

// All the other data present in the axios response
...
}

In the case of a bulk call the response data is an Array containing the response for each request (in the same order that the requests where passed)

let result = await anyBulkCall([{configs}]

//Result data will contain an array of responses
result.data.forEach(response=>{
   console.log (response)
})

// If an alias where provided for any request then that request could be accessed with that alias
let result = await anyBulkCall([{alias:'a',...},{alias:'b',...}]
console.log(result.data.a)
console.log(result.data.b)

Global Configuration

Configuration of the overall behaviour for the extension.

Note: The configuration could be made outside of a Vue component: See the: Use outside a Vue component

// Inside any Vue componente

// `baseURL` will be prepended to any path provided unless the provided path is absolute.
this.$api.baseURL = ''; // Empty string is the default

// The amount of attempts a request will make in the case of a timeout before failing completely
this.$api.maxAttemptsPerCall = 1; // 1 is the default

// The amount of concurrent requests that could be executed (when the requests number exceed this amount the requests are enqueue in a waiting mode)
this.$api.simultaneousCalls = 5; // 5 is the default

// Specifies the number of milliseconds before a request times out
this.$api.timeout = 10000; // 10000 is the default

// Sets the default headers for 'Content-Type' for each request
this.$api.setContentType('application/json') // 'application/json' is the default

// Sets the default authorization header: 'Authorization' for each request
this.$api.setAuthorization('token', 'Bearer') // The default is not to have any Authorization header

// If the store where not provided in the Quasar boot phase then it could be assigned to the extension using the next function
// This will bring the module 'APIwrapper' available and the extension will start updating its state
this.$api.setStore(vuex_instance) // vuex_instance should be a valid Vuex instance