This project is no longer maintained.

Using YAML to define code snippets is a terrible idea. I don't know what I was thinking.

Check out fastify-vite and fastify-api for a better path forward.

API clients should be autogenerated from the server code that implements them.

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 yamlful-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.