@zakkudo/open-api-tree

Make working with backend api trees enjoyable from swagger/openapi.

Generate an easy to use api tree that includes format checking using JSON Schema for the body and params with only a single configuration object. Network calls are executed using a thin convenience wrapper around fetch.

This library is a thin wrapper for @zakkudo/api-tree if you need the same functionality but don't use Swagger.

Why use this?

• Consistancy with simplicity
• No longer need to maintain a set of functions for accessing apis
• Automatic validation of the body/params against the Swagger definition
• Support for Swagger 1.2, Swagger 2.0 and OpenApi 3.0.x definitions
• Leverages native fetch, adding a thin convenience layer in the form of Fetch Functions
• Share authorization handling using a single location that can be updated dynamically
• Share a single transform for the responses and request in a location that can be updated dynamically
• Supports overloading the tree methods so that you can use the same method for getting a single item or a collection of items

The api tree is based off of the path name

• [POST] /users -> api.users.post({body: data})
• [GET] /users/{id} -> api.users.get({params: {id: 1}})
• [GET] /users -> api.users.get()
• [PUT] /users/{id} -> api.users.put({params: {id: 1}, body: data})
• [GET] /users/{userId}/roles/{roleId} -> api.users.roles.get({params: {userId: 1, roleId: 3}})

Install

# Install using npm
npm install @zakkudo/open-api-tree

# Install using yarn
yarn add @zakkudo/open-api-tree

Examples

Parse a swagger schema at runtime

import OpenApiTree from '@zakkudo/open-api-tree';
import fetch from '@zakkudo/fetch';

fetch('https://petstore.swagger.io/v2/swagger.json').then((configuration) => {
    const api = new OpenApiTree(configuration, {
        headers: {
             'X-AUTH-TOKEN': '1234'
        }
    });

    // GET http://petstore.swagger.io/api/pets?limit=10
    api.pets.get({params: {limit: 10}})

    // GET http://petstore.swagger.io/api/pets/1
    api.pets.get({params: {id: 1}})

    // POST http://petstore.swagger.io/api/pets
    api.pets.post({})

    // DELETE http://petstore.swagger.io/api/pets/1
    api.pets.delete({params: {id: 1}});
});

Parse a swagger schema at buildtime in webpack

//In webpack.conf.js////////////////////////////
import ApiTree from '@zakkudo/api-tree';

const toApiTreeSchema = require('@zakkudo/open-api-tree/toApiTreeSchema').default;
const execSync = require('child_process').execSync;
const configuration = JSON.parse(String(execSync('curl https://petstore.swagger.io/v2/swagger.json'));

module.exports = {
    plugins: [
        new DefinePlugin({
            __API_CONFIGURATION__: JSON.stringify(toApiTreeSchema(configuration))
        })
    }
}

//In src/api.js////////////////////////////////
import ApiTree from '@zakkudo/api-tree';

export default new ApiTree(__API_CONFIGURATION__);

//In src/index.js////////////////////////////
import api from './api';

// GET http://petstore.swagger.io/api/pets?limit=10
api.pets.get({params: {limit: 10}})

// GET http://petstore.swagger.io/api/pets/1
api.pets.get({params: {id: 1}})

// POST http://petstore.swagger.io/api/pets
api.pets.post({})

// DELETE http://petstore.swagger.io/api/pets/1
api.pets.delete({params: {id: 1}});

Validation error failure example

import ValidationError from '@zakkudo/open-api-tree/ValidationError';

api.pets.get({params: {id: 'lollipops'}}).catch((reason) => {
    if (reason instanceof ValidationError) {
        console.log(reason)
        // ValidationError: [
        //     "<http://petstore.swagger.io/api/pets/:id> .params.id: should be integer"
        // ]
    }

    throw reason;
});

Handling validation errors

import ValidationError from '@zakkudo/open-api-tree/ValidationError';

// Try fetching without an id
api.users.get().catch((reason) => {
    if (reason instanceof ValidationError) {
        console.log(reason); // "params: should have required property 'userId'
    }

    throw reason;
})

// Try using an invalidly formatted id
api.users.get({params: {userId: 'invalid format'}}).catch((reason) => {
    if (reason instanceof ValidationError) {
        console.log(reason); // "params.userId: should match pattern \"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\""
    }

    throw reason;
});

// Skip the validation by passing false to the network call
api.users.get({params: {userId: 'invalid format'}}, false).catch((reason) => {
    if (reason instanceof HttpError) {
        console.log(reason.status); // 500
    }

    throw reason;
});

Don't include validation schemas in api tree

import OpenApiTree from '@zakkudo/open-api-tree';
import HttpError from '@zakkudo/open-api-tree/HttpError';

fetch('https://petstore.swagger.io/v2/swagger.json').then((configuration) => {
    const api = new OpenApiTree(configuration, {
        headers: {
             'X-AUTH-TOKEN': '1234'
        }
    }, {validation: false});

    // Try fetching without an id
    api.users.get().catch((reason) => {
        if (reason instanceof HttpError) {
            console.log(reason.status); // 500
        }

        throw reason;
    })

    // Try using an invalidly formatted id
    api.users.get({params: {userId: 'invalid format'}}).catch((reason) => {
        if (reason instanceof HttpError) {
            console.log(reason.status); // 500
        }

        throw reason;
    });

    // Skip the validation by passing false to the network call
    api.users.get({params: {userId: 'invalid format'}}, false).catch((reason) => {
        if (reason instanceof HttpError) {
            console.log(reason.status); // 500
        }

        throw reason;
    });
});

Handling network errors

import HttpError from '@zakkudo/open-api-tree/HttpError';

// Force execution with an invalidly formatted id
api.users.get({params: {userId: 'invalid format'}}, false).catch((reason) => {
    if (reason instanceof HttpError) {
        console.log(reason.status); // 500
        console.log(reason.response); // response body from the server, often json
    }

    throw reason;
});

Overriding options

import HttpError from '@zakkudo/open-api-tree/HttpError';
import ValidationError from '@zakkudo/open-api-tree/ValidationError';

//Set headers after the fact
api.options.headers['X-AUTH-TOKEN'] = '5678';

//Get 10 users
api.users.get({params: {limit: 10}}).then((users) => {
     console.log(users); // [{id: ...}, ...]
});

//Create a user
api.users.post({first_name: 'John', last_name: 'Doe'}).then((response) => {
     console.log(response); // {id: 'ff599c67-1cac-4167-927e-49c02c93625f', first_name: 'John', last_name: 'Doe'}
});

// Try using a valid id
api.users.get({params: {userId: 'ff599c67-1cac-4167-927e-49c02c93625f'}}).then((user) => {
     console.log(user); // {id: 'ff599c67-1cac-4167-927e-49c02c93625f', first_name: 'john', last_name: 'doe'}
})

// Override the global options at any time
api.users.get({transformResponse: () => 'something else'}).then((response) => {
   console.log(response); // 'something else'
});

API

@zakkudo/open-api-tree~OpenApiTree ⏏

Kind: Exported class

• ~OpenApiTree
  • new OpenApiTree(schema, [options], [include])
  • ~FetchFunction : function
  • ~Options : Object

new OpenApiTree(schema, [options], [include])

Returns: Object - The generated api tree

| Param | Type | Default | Description | | --- | --- | --- | --- | | schema | Object | | The swagger/openapi schema, usually accessible from a url path like v2/swagger.json where swagger is run | | [options] | Options | | Options modifying the network call, mostly analogous to fetch | | [include] | Object | | Modifiers for the conversion of the swagger schema to an api tree schema | | [include.validation] | Boolean | true | Set to false to not include json schemas for client side validation of api requests |

OpenApiTree~FetchFunction : function

Executes the network request using the api tree configuration. Generated from the triplets of the form [url, options, jsonschema] where only url is required.

Kind: inner typedef of OpenApiTree

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Options | | The override options for the final network call | | [validate] | Boolean | true | Set to false to force validation to be skipped, even if there is a schema |

OpenApiTree~Options : Object

Options modifying the network call, mostly analogous to fetch

Kind: inner typedef of OpenApiTree
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | [options.method] | String | 'GET' | GET, POST, PUT, DELETE, etc. | | [options.mode] | String | 'same-origin' | no-cors, cors, same-origin | | [options.cache] | String | 'default' | default, no-cache, reload, force-cache, only-if-cached | | [options.credentials] | String | 'omit' | include, same-origin, omit | | [options.headers] | String | | "application/json; charset=utf-8". | | [options.redirect] | String | 'follow' | manual, follow, error | | [options.referrer] | String | 'client' | no-referrer, client | | [options.body] | String | Object | | JSON.stringify is automatically run for non-string types | | [options.params] | String | Object | | Query params to be appended to the url. The url must not already have params. The serialization uses the same rules as used by @zakkudo/query-string | | [options.unsafe] | Boolean | | Disable escaping of params in the url | | [options.transformRequest] | function | Array.<function()> | | Transforms for the request body. When not supplied, it by default json serializes the contents if not a simple string. Also accepts promises as return values for asynchronous work. | | [options.transformResponse] | function | Array.<function()> | | Transform the response. Also accepts promises as return values for asynchronous work. | | [options.transformError] | function | Array.<function()> | | Transform the error response. Return the error to keep the error state. Return a non Error to recover from the error in the promise chain. A good place to place a login handler when recieving a 401 from a backend endpoint or redirect to another page. It's preferable to never throw an error here which will break the error transform chain in a non-graceful way. Also accepts promises as return values for asynchronous work. |

@zakkudo/open-api-tree/toApiTreeSchema~toApiTreeSchema(schema, [include]) ⇒ Object ⏏

Converts an open-api/swagger schema to an api tree configuration.

Kind: Exported function

Returns: Object - The converted schema that can be passed to ApiTree from @zakkudo/api-tree
Throws:

• Error when trying to convert an unsupported schema

| Param | Type | Default | Description | | --- | --- | --- | --- | | schema | Object | | The schema as such that comes from swagger.json | | [include] | Object | | Modifiers for the conversion of the swagger schema to an api tree schema | | [include.validation] | Boolean | true | Set to false to not include json schemas for client side validation of api requests |

@zakkudo/open-api-tree/ValidationError~ValidationError ⏏

Aliased error from package @zakkudo/api-tree/ValidationError

Kind: Exported class

@zakkudo/open-api-tree/HttpError~HttpError ⏏

Aliased error from package @zakkudo/api-tree/HttpError

Kind: Exported class

@zakkudo/open-api-tree/UrlError~UrlError ⏏

Aliased error from package @zakkudo/api-tree/UrlError

Kind: Exported class

@zakkudo/open-api-tree/QueryStringError~QueryStringError ⏏

Aliased error from package @zakkudo/api-tree/QueryStringError

Kind: Exported class