Merge pull request mrichar1#54 from mrichar1/axios_conf

Refactor axios to allow more config overrides.

Author: mrichar1

README.md

@@ -15,6 +15,7 @@ A module to access [JSONAPI](https://jsonapi.org) data from an API, using a Vuex
 - Uses [jsonpath](https://github.com/dchester/jsonpath) for filtering when getting objects from the store.
 - Records the status of actions (LOADING, SUCCESS, ERROR).
 - New data can overwrite, or be merged onto, existing records. (See [mergeRecords](#Configuration))
+- Override endpoint names per-request (for plural names etc). (See [Endpoints](#Endpoints))
 
 ## Setup
 
@@ -56,6 +57,8 @@ There are a number of features which are worth explaining in more detail. Many o
 
 - _Preserve JSON_ - The original JSONAPI record(s) can optionally be preserved in `_jv` if needed - for example if you need access to `meta` or other sections. To avoid duplication, the `data` section (`attributes`, `relationships` etc) is removed.
 
+- _Endpoints_ - by default this module assumes that object types and API endpoints (item and collection) all share the same name. however, some APIs use plurals or other variations on the endpoint names. You can override the endpoint name via the `axios` `url` config option (see [Endpoints](#endpoints))
+
 ### Actions
 
 The usual way to use this module is to use `actions` wherever possible. All actions are asynchronous, and both query the API and update the store, then return data in a normalized form. Every action call's state is tracked as it progresses, and this status can be easily queried (see the `status` getter).
@@ -373,6 +376,43 @@ For many of these options, more information is provided in the [Usage](#usage) s
 - `actionStatusCleanAge` - What age must action status records be before they are removed (defaults to 600 seconds). Set to `0` to disable.
 - `mergeRecords`- Whether new records should be merged onto existing records in the store, or just replace them (defaults to `false`).
 
+## Endpoints
+
+By default `jsonapi-vuex` assumes that object type and API endpoint are the same. For example, `type: person` would have endpoint URLs of `/person` and `/person/1` for collections and single items.
+
+However many APIs vary how endpoints are named - for example plurals (e.g. `type:person`, `/person/1` and `/people`), or cases where the endpoint doesn't match the type (e.g. `type: person` `/author` and `/author/1`) or even a combination (e.g. `type: person` `/author/1` and `/authors`)
+
+To solve this it is possible to override the endpoint for a request by explicitly setting the `axios` `url` configuration option:
+
+```
+data = { _jv: { type: 'person' } }
+
+// Default behaviour - will always treat type = itemEP = collectionEP
+this.$store.dispatch('jv/get', data)
+// GETs /person
+
+// Explicitly override the endpoint url
+this.$store.dispatch('jv/get', [data, { url: '/people' }])
+
+this.$store.dispatch('jv/get', [data, { url: '/author/1' }])
+
+// Override using a dynamic function
+const customUrl = (data) => {
+  if (data.hasOwnProperty('id')) {
+    // single item (singular)
+    return `person/${data.id}`
+  } else {
+    // collection (plural)
+    return '/people'
+  }
+}
+
+this.$store.dispatch('jv/get', [{ _jv: { type: 'widget' } }, { url: customUrl(data) }])
+
+```
+
+_Note_ - If provided the `url` option is used as-is - you are responsible for setting a valid collection or item url (with `id`) as appropriate.
+
 ## Restructured Data
 
 JSONAPI is an extremely useful format for clearly interacting with an API - however it is less useful for the end developer, who is generally more interested in the data contained in a record than the structure surrounding it.

src/jsonapi-vuex.js

@@ -68,12 +68,13 @@ const actions = (api) => {
     get: (context, args) => {
       const [data, config] = unpackArgs(args)
       const path = getURL(data)
+      const apiConf = { method: 'get', url: path }
       // https://github.com/axios/axios/issues/362
       config['data'] = config['data'] || {}
+      merge(apiConf, config)
       const actionId = actionSequence(context)
       context.commit('setStatus', { id: actionId, status: STATUS_LOAD })
-      let action = api
-        .get(path, config)
+      let action = api(apiConf)
         .then((results) => {
           processIncludedRecords(context, results)
 
@@ -185,10 +186,11 @@ const actions = (api) => {
     post: (context, args) => {
       let [data, config] = unpackArgs(args)
       const path = getURL(data, true)
+      const apiConf = { method: 'post', url: path, data: normToJsonapi(data) }
+      merge(apiConf, config)
       const actionId = actionSequence(context)
       context.commit('setStatus', { id: actionId, status: STATUS_LOAD })
-      let action = api
-        .post(path, normToJsonapi(data), config)
+      let action = api(apiConf)
         .then((results) => {
           processIncludedRecords(context, results)
 
@@ -215,9 +217,10 @@ const actions = (api) => {
       let [data, config] = unpackArgs(args)
       const path = getURL(data)
       const actionId = actionSequence(context)
+      const apiConf = { method: 'patch', url: path, data: normToJsonapi(data) }
+      merge(apiConf, config)
       context.commit('setStatus', { id: actionId, status: STATUS_LOAD })
-      let action = api
-        .patch(path, normToJsonapi(data), config)
+      let action = api(apiConf)
         .then((results) => {
           // If the server handed back data, store it
           if (results.status === 200) {
@@ -249,10 +252,11 @@ const actions = (api) => {
     delete: (context, args) => {
       const [data, config] = unpackArgs(args)
       const path = getURL(data)
+      const apiConf = { method: 'delete', url: path }
+      merge(apiConf, config)
       const actionId = actionSequence(context)
       context.commit('setStatus', { id: actionId, status: STATUS_LOAD })
-      let action = api
-        .delete(path, config)
+      let action = api(apiConf)
         .then((results) => {
           processIncludedRecords(context, results)
 

tests/unit/actions/delete.spec.js

@@ -37,7 +37,15 @@ describe('delete', function() {
       { params: params },
     ])
 
-    expect(this.mockApi.history.delete[0].params).to.equal(params)
+    expect(this.mockApi.history.delete[0].params).to.deep.equal(params)
+  })
+
+  it('should allow the endpoint url to be overridden in config', async function() {
+    this.mockApi.onAny().reply(200, { data: jsonWidget1 })
+    const url = '/fish/1'
+
+    await jsonapiModule.actions.delete(stubContext, [normWidget1, { url: url }])
+    expect(this.mockApi.history.delete[0].url).to.equal(url)
   })
 
   it('should delete a record from the store', async function() {

tests/unit/actions/get.spec.js

@@ -81,8 +81,15 @@ describe('get', function() {
       normWidget1,
       { params: params },
     ])
+    expect(this.mockApi.history.get[0].params).to.deep.equal(params)
+  })
+
+  it('should allow the endpoint url to be overridden in config', async function() {
+    this.mockApi.onAny().reply(200, { data: jsonWidget1 })
+    const url = '/fish/1'
 
-    expect(this.mockApi.history.get[0].params).to.equal(params)
+    await jsonapiModule.actions.get(stubContext, [normWidget1, { url: url }])
+    expect(this.mockApi.history.get[0].url).to.equal(url)
   })
 
   it('should add record(s) in the store', async function() {

tests/unit/actions/patch.spec.js

@@ -52,7 +52,15 @@ describe('patch', function() {
       { params: params },
     ])
 
-    expect(this.mockApi.history.patch[0].params).to.equal(params)
+    expect(this.mockApi.history.patch[0].params).to.deep.equal(params)
+  })
+
+  it('should allow the endpoint url to be overridden in config', async function() {
+    this.mockApi.onAny().reply(200, { data: jsonWidget1 })
+    const url = '/fish/1'
+
+    await jsonapiModule.actions.patch(stubContext, [normWidget1, { url: url }])
+    expect(this.mockApi.history.patch[0].url).to.equal(url)
   })
 
   it('should delete then add record(s) in the store (from server response)', async function() {

tests/unit/actions/post.spec.js

@@ -38,7 +38,15 @@ describe('post', function() {
       { params: params },
     ])
 
-    expect(this.mockApi.history.post[0].params).to.equal(params)
+    expect(this.mockApi.history.post[0].params).to.deep.equal(params)
+  })
+
+  it('should allow the endpoint url to be overridden in config', async function() {
+    this.mockApi.onAny().reply(200, { data: jsonWidget1 })
+    const url = '/fish/1'
+
+    await jsonapiModule.actions.post(stubContext, [normWidget1, { url: url }])
+    expect(this.mockApi.history.post[0].url).to.equal(url)
   })
 
   it('should add record(s) to the store', async function() {