rework api module and add doc

app/src/helpers/api.js

@@ -1,14 +1,37 @@
+/**
+ * api module.
+ * @module api
+ */
+
 import store from '@/store'
 
-function objectToParams (object) {
-  const urlParams = new URLSearchParams('locale=' + store.getters.locale)
+/**
+ * Converts an object literal into an `URLSearchParams` that can be turned into a
+ * query string or used as a body in a `fetch` call.
+ *
+ * @param {Object} object - An object literal to convert.
+ * @param {Object} options
+ * @param {boolean} [options.addLocale=false] - Option to append the locale to the query string.
+ * @return {URLSearchParams}
+ */
+export function objectToParams (object, { addLocale = false } = {}) {
+  const urlParams = new URLSearchParams()
   for (const [key, value] of Object.entries(object)) {
     urlParams.append(key, value)
   }
+  if (addLocale) {
+    urlParams.append('locale', store.getters.locale)
+  }
   return urlParams
 }
 
-async function handleResponse (response) {
+/**
+ * Handler for api responses.
+ *
+ * @param {Response} response - A fetch `Response` object.
+ * @return {DigestedResponse} Parsed response's json, response's text or an error.
+ */
+export async function handleResponse (response) {
   if (!response.ok) return handleErrors(response)
   // FIXME the api should always return json objects
   const responseText = await response.text()
@@ -19,7 +42,13 @@ async function handleResponse (response) {
   }
 }
 
-async function handleErrors (response) {
+/**
+ * Handler for API errors.
+ *
+ * @param {Response} response - A fetch `Response` object.
+ * @throws Will throw an error with the API response text or custom message.
+ */
+export async function handleErrors (response) {
   if (response.status === 401) {
     throw new Error('Unauthorized')
   } else if (response.status === 400) {
@@ -28,6 +57,15 @@ async function handleErrors (response) {
   }
 }
 
+/**
+ * A digested fetch response as an object, a string or an error.
+ * @typedef {(Object|string|Error)} DigestedResponse
+ */
+
+/**
+ * Actual api module.
+ * @module api/default
+ */
 export default {
   options: {
     credentials: 'include',
@@ -43,38 +81,78 @@ export default {
     }
   },
 
-  get (uri, urlParams = {}) {
-    return fetch(
-      `/api/${uri}?${objectToParams(urlParams)}`,
-      this.options
-    ).then(handleResponse)
+  /**
+   * Generic method to fetch the api without automatic response handling.
+   *
+   * @param {string} method - a method between 'GET', 'POST', 'PUT' and 'DELETE'.
+   * @param {string} uri
+   * @param {string} [data={}] - data to send as body for 'POST', 'PUT' and 'DELETE' methods.
+   * @return {Promise<Response>} Promise that resolve a fetch `Response`.
+   */
+  fetch (method, uri, data = {}) {
+    if (method === 'GET') {
+      const localeQs = `${uri.includes('?') ? '&' : '?'}locale=${store.getters.locale}`
+      return fetch('/api/' + uri + localeQs, this.options)
+    }
+    return fetch('/api/' + uri, {
+      ...this.options,
+      method,
+      body: objectToParams(data, { addLocale: true })
+    })
   },
 
+  /**
+   * Api get helper function.
+   *
+   * @param {string} uri - the uri to call.
+   * @return {Promise<module:api~DigestedResponse>} Promise that resolve the api response as an object, a string or as an error.
+   */
+  get (uri) {
+    return this.fetch('GET', uri).then(handleResponse)
+  },
+
+  /**
+   * Api get helper function for multiple queries.
+   *
+   * @param {string} uri - the uri to call.
+   * @return {Promise<module:api~DigestedResponse[]>} Promise that resolve the api responses as an array.
+   */
   getAll (uris) {
-    return Promise.all(uris.map((uri) => this.get(uri)))
+    return Promise.all(uris.map(uri => this.get(uri)))
   },
 
+  /**
+   * Api post helper function.
+   *
+   * @param {string} uri - the uri to call.
+   * @param {string} [data={}] - data to send as body.
+   * @return {Promise<module:api~DigestedResponse>} Promise that resolve the api responses as an array.
+   */
   post (uri, data = {}) {
-    return fetch('/api/' + uri, {
-      ...this.options,
-      method: 'POST',
-      body: objectToParams(data)
-    }).then(handleResponse)
+    return this.fetch('POST', uri, data).then(handleResponse)
   },
 
+  /**
+   * Api put helper function.
+   *
+   * @param {string} uri - the uri to call.
+   * @param {string} [data={}] - data to send as body.
+   * @return {Promise<module:api~DigestedResponse>} Promise that resolve the api responses as an array.
+   */
   put (uri, data = {}) {
-    return fetch('/api/' + uri, {
-      ...this.options,
-      method: 'PUT',
-      body: objectToParams(data)
-    }).then(handleResponse)
+    return this.fetch('PUT', uri, data).then(handleResponse)
   },
 
+  /**
+   * Api delete helper function.
+   *
+   * @param {string} uri - the uri to call.
+   * @param {string} [data={}] - data to send as body.
+   * @return {Promise<('ok'|Error)>} Promise that resolve the api responses as an array.
+   */
   delete (uri, data = {}) {
-    return fetch('/api/' + uri, {
-      ...this.options,
-      method: 'DELETE',
-      body: objectToParams(data)
-    }).then(response => response.ok ? 'ok' : handleErrors(response))
+    return this.fetch('DELETE', uri, data).then(response => {
+      return response.ok ? 'ok' : handleErrors(response)
+    })
   }
 }

app/src/store/data.js

@@ -102,14 +102,14 @@ export default {
         const currentState = param ? state[storeKey][param] : state[storeKey]
         // if data has already been queried, simply return the state as cached
         if (currentState !== undefined && !force) {
-          return { cached: true, responseData: currentState }
+          return { cached: currentState }
         }
         return api.get(param ? `${uri}/${param}` : uri).then(responseData => {
           return { storeKey, param, responseData }
         })
       })).then(responsesData => {
-        return responsesData.map(({ storeKey, param, responseData, cached = false }) => {
-          if (cached) return responseData
+        return responsesData.map(({ storeKey, param, responseData, cached = null }) => {
+          if (cached) return cached
           const data = responseData[storeKey] ? responseData[storeKey] : responseData
           commit('SET_' + storeKey.toUpperCase(), param ? [param, data] : data)
           return param ? state[storeKey][param] : state[storeKey]
@@ -135,7 +135,7 @@ export default {
       })
     },
 
-    'DELETE' ({ state, commit }, { uri, param, data = {}, storeKey = uri }) {
+    'DELETE' ({ commit }, { uri, param, data = {}, storeKey = uri }) {
       return api.delete(param ? `${uri}/${param}` : uri, data).then(() => {
         commit('DEL_' + storeKey.toUpperCase(), param)
       })

app/src/views/service/ServiceInfo.vue

@@ -151,9 +151,8 @@ export default {
         ? `services/${this.name}/restart`
         : 'services/' + this.name
 
-      api[method](uri).catch(() => {
-        // FIXME API doesn't return anything to the PUT so => json err
-      }).finally(() => {
+      // FIXME API doesn't return anything to the PUT so => json err
+      api.fetch(method, uri).then(() => {
         this.fetchData()
       })
     },

app/src/views/tool/ToolLog.vue

@@ -58,7 +58,7 @@
 </template>
 
 <script>
-import api from '@/helpers/api'
+import api, { objectToParams } from '@/helpers/api'
 import { readableDate } from '@/filters/date'
 
 export default {
@@ -90,13 +90,13 @@ export default {
 
   methods: {
     fetchData () {
-      const params = {
+      const queryString = objectToParams({
         path: this.name,
         filter_irrelevant: '',
         number: this.numberOfLines
-      }
+      })
 
-      api.get('logs/display', params).then(log => {
+      api.get('logs/display?' + queryString).then(log => {
         if (log.logs.length === this.numberOfLines) {
           this.moreLogsAvailable = true
           this.numberOfLines *= 10

app/src/views/tool/ToolLogs.vue

@@ -60,7 +60,7 @@ export default {
   methods: {
     fetchData () {
       // FIXME only prints operation for now (can't receive 'history', 'app', 'service', etc.)
-      api.get('logs', { limit: 25, with_details: '' }).then(({ operation }) => {
+      api.get(`logs?limit=${25}&with_details`).then(({ operation }) => {
         operation.forEach((log, index) => {
           if (log.success === '?') {
             operation[index].icon = 'question'

app/vue.config.js

@@ -40,7 +40,7 @@ module.exports = {
     i18n: {
       locale: 'en',
       fallbackLocale: 'en',
-      localeDir: 'locales',
+      localeDir: 'src/i18n/locales',
       enableInSFC: false
     }
   },