api-master

Backend API validation and documentation framework.

Usage no npm install needed!

<script type="module">
  import apiMaster from 'https://cdn.skypack.dev/api-master';
</script>

README

Uses schema for:

  • Validating API-methods parameter and result
  • Generating API documentation (Warning: not implemented yet)

Features

  • Schema: Joi (could be converted to JSON-Schema over joi-to-json-schema)
  • API-call parameter validation
  • API-call result validation
  • Errors:
    • All valid API errors extracted to one place
    • True type errors (inherits Error and ApiError)
    • Contains statusCode
    • Default error properties specification
    • Custom error parameters
  • api-master API:
    • Chaining for synchronous api.* methods
    • Potentially asynchronous api.call() returns promise

Installation

npm install api-master --save

Run tests

npm install -g gulp

cd node_modules/api-master/

gulp test

Usage example

See example sources in node_modules/api-master/test/readme/

node node_modules/api-master/test/readme/use.js

Define API Errors

api/errors.js

module.exports = function(api) {
    return api
        .errType(500, 'SuperBackendError', function(err, data) {
            err.message = 'Sorry guys but data is ' + data
        })
        .errType(500, 'PropsError', {message: 'msg', myInfo: 123})
        .errType(500, 'SimpleError', 'Just a message')
    // ...
}

Define API Methods (End-Points)

api/methods.js

var Joi = require('joi')

module.exports = function(api) {
    return api
        .method('checkData', {
            description: 'Checks given data', // Optional additional short description
            param: Joi.object().required().keys({
                data: Joi.bool().required().description('Data to check')
            }),
            result: Joi.string().required().description('Message about data'),
            impl: function(param, helper) {
                if(param.data == true) {
                    helper.resolve('Data is ok')
                } else {
                    helper.reject('SuperBackendError', param.data) // Uses defined error type
                }
            }
        })
    // ...
}

Use API

// Define API
var api = require('api-master').makeApi('Super Backend')

require('./api/methods')(api)
require('./api/errors')(api)

// Use API
var methodName = 'checkData'


function testCall(param) {
    var callData = {} // optional call data: req, res, session, user

    api.call(methodName, param, callData)
        .then(function(result) {
            console.log('Result:', result)
        })
        .catch(function(err) {
            console.log('Catched:', err.stack)
        })
        .done()
}

testCall({data: true}) // Data is ok

testCall({data: false}) // SuperBackendError: Sorry guys but data is false