vue-api-generator

Vue Inner API plugin generator

Install

install local

npm i vue-api-generator --save-dev

install global

npm i -g vue-api-generator

Generating

Once installed, one can execute the npm vue-api-generator in order to generate the plugin api.

A configuration file is required in order to give instructions on how to generate the api plugin.

By default, the configuration file will be picked from the working directory file configuration.json but it is possible to specify a configuration file path using npm vue-api-generator <config file path>

using server generation

In this mode, one can open th server in any terminal and let it run while updating the api configuration file. The server will automatically regenerate the api plugin every time the api configuration file is updated.

npm vue-api-generator-server <config file path>

configuration file

Specification

• name? (string api name, default is api, optional)
• credentials_path? (string credential json file path, optional)
• vue_src_directory? (string vue source directory path, default is ./src, optional)
• is_fake? (boolean put the api generator into fake mode or not, default is false, optional)
• apis (object apis config)
  • name (string api name, us "" for direct access) → (object)
    • host (string api main host)
    • apis? (apis for sub apis, optional)
    • endpoints? (objects all endpoints, opional)
      • ep_url_pattern (string) → (object)
        • url (string uses express pattern)
        • method? (string REST method, default is GET, optional)
        • default? (string default value for all url arguments, optional)
        • defaults? (object default values specified for each url argument, overrides the default value if set)
          • arg_name (string) → (string default value)
        • data_needed? (boolean whether a data body is needed or not, optional)
        • data_format? (string if data is needed, specify the data format, default is json, optional)
        • credentials? (object credential to use)
          • header_type (string see header types)
          • token_type (string see token types)
          • options (credential options)
        • fake_response (object fake json response if api in fake mode, optional)
        • fake_code (object fake status code and text if api in fake mode, optional)
          • status (integer status code)
          • statusText (string status text)

Fake Mode

One can enable the fake mode api by setting the root configuration property is_fake to true.
In fake mode, the api will only answer using the fake_response present in each endpoint (or {} if not set).

Credentials

The main credential file containing all credentials data must be specified in the root key credentials_path. Leave this key blank or unexistent if you have no credentials to be imprinted inside the api plugin.

The credential endpoint object uses a credential options key data in order to setup the credential headers for a specific endpoint.

This options object's content depends on the credential header and token types.

header types

• Bearer creates an Authorization header { Authorization: "Bearer <token>" }
• Custom creates a custom name header { <options.header>: "<token>" }

token types

• absolute creates an Authorization header { <cred_header>: this.credentials["<options.cred_key>"] }
  You will have to provide a credential file path containing the specified credential key cred_key in the configuration file. Bear in mind that these credentials will be imprinted inside the client api thus being accessible by an client. Only client side api tokens must be delivered through the credentials file.
• argument gets token from endpoint function argument { <cred_header>: <options.argument> }
• cookie uses the client cookie to setup the token { <cred_header>: this.__get_cookie("<options.cookie>") }
• session uses the client sessionStrage to setup the token { <cred_header>: sessionStorage("<options.cred_key>") }
• local uses the client localStorage to setup the token { <cred_header>: localStorage("<options.cred_key>") }
• local_session uses the client localStorage or sessionStorage to setup the token { <cred_header>: (localStorage("<options.cred_key>") ?? sessionStorage("<options.cookie>")) }

Sub Apis

When a sub api is specified using the apis key within an API configuration, all host are concatenated.

The API names will have to be called in chain this.$api.root_api.sub_api.sub_sub_api ....

A root api can be configured to use endpoints has well as sub apis.

Environnement Variables

One can ask the api generator to imprint a given variable environnement (eather from at serve time or at build time) by specifying the varenv name preceded by to ENV: keyword.
For example, if one need to use a custome host specified by an environnement variable, the configuration looks like this host: "https://ENV:MAIN_HOST/apis".

Many ENV:... instructions can be used in a single string.

The ENV:... instruction can be use in any given string (except in keys from the configuration file).

Example

1{
2    "name": "my_api",
3    "credentials_path": "./my_creds.json",
4    "vue_src_directory": "./src",
5    "apis": {
6        "accounts": {
7            "host": "/api",
8            "endpoints": {
9                "list": {
10                    "url": "",
11                    "method": "GET"
12                },
13                "create": {
14                    "url": "/:name",
15                    "method": "POST",
16                    "data_needed": true
17                }
18            }
19        },
20        "facebook": {
21            "host": "https://api.facebook.com/api",
22            "apis": {
23                "people": {
24                    "host": "people/v1",
25                    "endpoints": {
26                        "get": {
27                            "url": ":name",
28                            "method": "GET",
29                            "credentials": {
30                                "header_type": "Bearer",
31                                "token_type": "absolute",
32                                "options": {
33                                    "cred_key": "facebook"
34                                }
35                            }
36                        }
37                    }
38                },
39                "connection": {
40                    "host": "peopleConnect/V3",
41                    "endpoints": {
42                        "get": {
43                            "url": ":id1/:id2",
44                            "method": "GET",
45                            "credentials": {
46                                "header_type": "Bearer",
47                                "token_type": "absolute",
48                                "options": {
49                                    "cred_key": "facebook"
50                                }
51                            }
52                        }
53                    }
54                }
55            }
56        }
57    }
58}

Usage

Commands

Documentation

npm exec vue-api-generator[ <JSON configuration file path>]

• JSON configuration file path to specify the api configuration file (default is "./configuration.json")

Examples

npm exec vue-api-generator

npm exec vue-api-generator "my_api_config.json"

npm exec vue-api-generator "./configs/my_api_config.json"

npm exec vue-api-generator "/home/devs/my_project/my_api_config.json"

JS

Using the configuration file above, one can use the described api inside a vue component using:

1
2methods: {
3
4    // ---- api v3 usage
5    async get_company_list() {
6        return await this.$my_api.get_companies()
7    },
8
9    async create_company(name, id, nic) {
10        const company = {id, name, nic}
11        await this.$my_api.create_company(company)
12        this.success_text = `company ${name} created !`
13    },
14    
15    async remove_company(id) {
16        const rm_company = await this.$my_api.remove_company(compidany)
17        this.success_text = `company ${rm_company.name} removed !`
18    },
19
20    // ---- api v0 usage
21    async update_data_list() {
22        const list = await this.$my_api.old_api.list()
23        this.$set(this, 'accounts', list)
24    },
25    async create_account(name, account_data={}) {
26        const new_account = await this.$my_api.old_api.create(name, account_data)
27        console.log('new account', name, 'created', new_account)
28        this.update_data_list()
29    },
30
31    // ---- facebook sub apis example
32    async connect_people(people1, people2) {
33        const { id: id1 } = people1
34        const { id: id2 } = people2
35        const created_link = await this.$my_api.facebook.connection.connect(id1, id2)
36    }
37}
38

License

Licensed under MIT