YAML-based HTTP client code generation
Switch branches/tags
Nothing to show
Clone or download
Latest commit 4d2d6b4 Dec 2, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
nuxt-example add nuxt example Nov 26, 2018
packages v0.3.6 Dec 2, 2018
.eslintignore fix linting settings Dec 2, 2018
.eslintrc 0.1.0 Nov 26, 2018
.gitignore package fix Nov 26, 2018
README.md allow for passing query params in Nuxt API methods (3) Dec 2, 2018
lerna.json v0.3.6 Dec 2, 2018
package.json fix linting settings Dec 2, 2018

README.md

yamlful is a utility for HTTP client code generation from YAML:

sample:
  - method: get
    get: /resource/:id/subresource/:subId
  - method: create
    post: /resource/:id/subresource
  - method: update
    put: /resource/:id/subresource/:subId
  - method: remove
    delete: myresource/

It uses a simple pattern to determine function arguments and HTTP parameters, so that methods that use PUT or POST get a payload and others don't, while preserving the URL parameters in each YAML-defined endpoint.

The above YAML file can be used to generate a snippet like this:

const sample = {
  get: (id, subId, params = {}) => {
    return client.get(`/resource/${id}/subresource/${subId}`, { params })
  },
  create: (id, payload, params = {}) {
    return client.post(`/resource/${id}/subresource`, payload, { params })
  },
  update: (id, subId, payload, params = {}) {
    return client.put(`/resource/${id}/subresource/${subId}`, payload, { params })
  },
  remove: (id, params = {}) => {
    return client.delete(`myresource/${id}`, { params })
  }
}

Motivation

Boilerplate JavaScript for exposing HTTP API client methods is pretty simple most of the time.

However, when you have a huge API with dozens of different resources, more streamlined YAML configuration makes it easier to maintain it while dealing with constant change. yamlful was born by identifying these key simple patterns when connecting JavaScrit methods to JSON HTTP APIs.

Nuxt.js module

Bundled in this repository is a Nuxt.js module (yamlful-nuxt) that uses yamlful to generate similar code, integrating itself to @nuxtjs/axios and exposing API methods to Vue pages.

npm install yamful-nuxt --save

In nuxt.config.js:

export default {
  // Thanks to Pooya Parsa for the awesome Nuxt Axios module
  // Note that @nuxtjs/axios is automatically required by yamlin
  axios: {
    // Thanks to Ben Howdle for the amazing API testing service
    baseURL: 'https://reqres.in/'
  },
  // By default, yamlful will look for .yml files in Nuxt's srcDir
  modules: ['yamlful-nuxt']
}

In pages/index.vue:

export default {
  async asyncData ({ $api }) {
    // $api available in SSR context
    const response = await $api.users.get(1)
    return {
      user: response.data
    }
  },
  data: () => ({
    user: {}
  }),
  methods: {
    async loadTwo() {
      // this.$api available in the client context
      const response = await this.$api.users.get(2)
      this.user = response.data
    }
  }
}

Raw methods

The Nuxt.js module also allows you to inline JavaScript in YAML for defining raw methods:

Input:

  - method: custom
    raw: |
      (customParam) => {
      	client.get(`/customresource/${customParam}`)
      }

Output:

  custom: (customParam) => {
    client.get(`/customresource/${customParam}`)
  }

Note that client is used to inject Nuxt's axios instance.

See the API template used for the Nuxt module.

Other frameworks

Modules and extensions for other frameworks can be implemented using the main exported function in the yamlful package. PRs are very much welcome.