koa-api-validator v1.0.0-beta.2

koa-api-validator

A middleware to easily build APIs with easy to read modular code

• Modular Programming Compatibility
• Validate input and output
• Easy to grasp Validator Notation
• Support async/await
• Increases readability and maintainability
• Event-Based Hooks
• Very easy to document

Installation

install via npm:

npm install koa-api-validator

Basic Usage

const Koa = require('koa')
const {ApiValidator} = require('koa-api-validator')
const commands = require('./api') // your api files
(async () => {
  const app = new Koa()
  const api = new ApiValidator(commands)
  app.use(await api.build())
})()

Getting Started

Koa-Api-Validator builds the api using commands

Command

A command is a JS Object, that store information about the API

there're three types of commands:

• Path : the path command is the main structure in the API, it defines the API endpoint that will be created.
• Validator : the validator command, is a command to build a Joi validator that will validate either the input or the output.
• Hook : the hook command defines a hook that use middleware in the specific path at the given event.

$reference

references allows commands to reference each-other out-of-the-box

the Path command can work stand-alone with all functionality as it supports adding inline validators and hooks, however Validators and Hooks must reference or be referenced in a Path

Build your first app

start a new project and install koa, koa-bodyparser, koa-api-validator via npm

npm i koa koa-bodyparser koa-api-validator

in your app.js

// app.js
const Koa = require('koa')
const bodyParser = require('koa-bodyparser')
const {ApiValidator} = require('koa-api-validator')
const apiCommands = require('./api')

(async () => { const app = new Koa() const api = new ApiValidator(apiCommands) app.use(bodyParser()) app.use(await api.build()) })()

create the directory `api`
and create the file `./api/myFirstEndpoint.js`
```javascript
// ./api/myFirstEndpoint.js
const path = {
    $type: 'path', // specify the $type of command as path, optional in paths
    $name: 'myFirstEndpoint', // we named the path to be able to reference it latter
    path: '/myfirstpath',
    method: 'GET',
    hooks: {
        'api': (ctx, next) => { // add api hook
            ctx.body = 'hello world' // here goes your api logic
            next() // all hooks must call next() after finishing
        }
    }
}

module.exports = path

we just created a path, learn more about Paths

now create an ./api/index.js to export our command to the app

// ./api/index.js
module.exporst = [
    require('./myFirstEndpoint')
]

now our app is finished it will respond with hello world when GETing /myfirstpath we can add an output validator to make sure our endpoint will always send a String create the file ./api/myFirstValidator.js

// ./api/myFirstValidator.js
const validator = {
    $type: 'validator', // the type of the command
    type: String, // the type of the validator
    $path: 'myFirstEndpoint', // adding this validator to the our path using a reference
    $rel : 'output' // adding this validator as an 'output' validator
}
module.exports = validator

we just created a validator command, learn more about Validators now we need to add it in our array of commands at index.js

// ./api/index.js
module.exporst = [
    require('./myFirstEndpoint'),
    require('./myFirstValidator')
]

and we're done. your project structure should be something like

│
├─ api
│   ├─ myFirstEndpoint.js
│   ├─ myFirstValidator.js
│   ╰─ index.js
├─ app.js
├─ node_modules
╰─ package.json

Modularity

Koa-Api-Validator helps making your code clean, easy-to-read, easy-to-maintain and modular, so in real-life application you can achieve a structure like:

│
╰─ api
    ├─ user
    │    ├─ register
    │    │    ├─ registerValidator.js
    │    │    ├─ outputValidator.js
    │    │    ├─ api.js
    │    │    ╰─ index.js
    │    ....
    ╰─ index.js

Documetation

You can find the full documentation in the Wiki

Contributing

Please submit all issues and pull requests to the k0hamed/koa-api-validator repository!