bebel

    1.1.4 • Public • Published

    Bebel — a simple http API builder

    Bebel is a simple, fast, and minimalist API builder. Bebel protocol is also a specification based on JSON format to define how a client should request, and how a server should respond to those requests. Bebel uses a functional paradigm, and can be used for computational sciences.

    Specification of bebel protocol

    Bebel query is sent via the post method of http.

    Bebel query

    [commandName, parameter]

    commandName: String [require] Name of the command to call.

    parameter: JSON object [optional] Parameter of the command (string, number, booolean, array or object value).


    Bebel response

    {
      code,
      info,
      body
    }

    code: String [require] Header response amont "success" or "error" values.

    info: String [require] Information intended to be read by a human.

    body: JSON object [require] Body response of the command.

    Examples of bebel transaction

    // query
    ["pi"]
    
    // response
    {
      "code": "success",
      "info": "π value",
      "body": 3.141592653589793
    }
    // query
    ["authenfication", {
      "login": "julien",
      "password": "Pa$sW0rD!"
    }]
    
    // response
    {
      "code": "success",
      "info": "Welcome Julien",
      "body": true
    }
    // query
    ["meteo", "montpellier"]
    
    // response
    {
      "code": "success",
      "info": "What a beautiful weather in Montpellier",
      "body": {
        "temperature": "26°",
        "humidity": "13%" 
      }
    }
    // query
    ["square", 10]
    
    // response
    {
      "code": "success",
      "info": "square executed",
      "body": 100
    }
    // query
    ["sum", [2, 3, 4]]
    
    // response
    {
      "code": "success",
      "info": "sum executed",
      "body": 9
    }

    By combining the two instructions square and sum commands :

    // query
    ["square", ["sum", [2, ["square", 3]]]]
    // equal to
    ["square", ["sum", [2, 9]]]
    // equal to
    ["square", 11]
    
    // response
    {
      "code": "success",
      "info": "square executed",
      "body": 121
    }

    Usage

    const Bebel = require('bebel')
    const directory = 'example'
    const port = 8000
    
    new Bebel({ directory })
      .listen(port)
      .start()

    API

    Creates a bebel API.

    const Bebel = require('bebel')
    const api = new Bebel(options)
    • options: Object
      • directory: String (default: 'root') Path of directory that contains all commands.

    Methods

    api.listen(port, https_param)
    • port: Number (default: 8000) Binds and listens for connections on the specified host and port.
    • https_param: Object (default: false)
      • key: String Path of private key.
      • cert: String Path of certificate.

    If https_param is omitted the server is started in http.


    api.start()

    Start bebel server, return result in a promise. By convention we call the result THIS :

    api.start()
      .then(THIS => {
        console.log(THIS.meteo("montpellier"))
      })

    We notice in this example that meteo command can be invoked directly as a function from the callback of the promise. THIS is an object which contains all the resources declared by the registry method. It also contains native methods like sessionStart invoked on each connection. sessionStart can be redefined by the registry method.


    api.registry(name, type, func)
    var api = new API({ directory })
    api.registry('square', 'command', x => x ** 2)
    api.start().then(THIS => {
      console.log(THIS.square(9))
    })
    • name: String Name of the resource.
    • method: String There are 3 types of resources to build a bebel API :
      • command defines a resource that can be called via a bebel query or directly as a function.
      • this defines a simple function that cannot be invoked via a bebel query.
      • instance defines a persistent object that can be called in any function or command.
    • func: Function or Class The Javascript code of a function for command and this resources. The Javascript code of a class for instance resources.

    Any javascript file present in the root directory will automatically be transformed into resources if it is named with the prefix command. or this. or instance. The project tree can be organized in a complex way, the search for resources is recursive.

    Example

    command.square.js :

    module.exports = function (x) {
      return x ** 2
    }

    defines a command named square.

    instance.shareObject.js :

    module.exports = class {
      constructor () {
        this.counter = 0
      }
    }

    defines an instance named shareObject.


    THIS

    All resources are directly linked to this object, it also has some native properties :

    • $express: Object Refers to the express instance that manages the http socket.

    • $query: Object Refers to the connexion of the command.

      • req: Object Express Request of query.
      • res: Object Express Response of query.
      • session: Object Session of connection.
      • command: String Name of the command.
      • param: Object Parameter of the command at bebel format.
      • response: Object Response of the command at bebel format.
    • $eventEmitter: Object

      • onStart This event is triggered when http(s) server starts.
      • beforeExec This event is triggered before command execution.
      • afterExec This event is triggered after command execution.
    • $rootDirectory: String Path of directory that contains all commands.

    Example

    To call a function before each command execution :

    api.start().then(THIS => {
      THIS.$eventEmitter.on('beforeExec', THIS => {
        console.log(`I : ${THIS.$query.command}`)
      })
    })

    However, it is preferable to link the events in an instance resource :

    instance.linkEvent.js

    module.exports = class {
      constructor (application) {
        application.$eventEmitter.on('onStart', THIS => THIS.onStart())
        application.$eventEmitter.on('beforeExec', THIS => THIS.beforeExec())
        application.$eventEmitter.on('afterExec', THIS => THIS.afterExec())
      }
    }

    Installation

    This is a Node.js module available through the npm registry.

    Before installing, download and install Node.js. Node.js 0.10 or higher is required.

    $ npm install bebel

    Features

    • Handling HTTP responses
    • Protocol based on a JSON object exchange
    • High performance
    • Supports HTTPS
    • Designed to minimize requests between clients and servers

    Examples

    To view the examples, clone the bebel-exemple repo and install the dependencies:

    $ git clone https://github.com/bebeljs/bebel.git
    $ cd bebel
    $ npm install
    $ npm run example

    View the website at: http://localhost:8000

    License

    MIT

    Install

    npm i bebel

    DownloadsWeekly Downloads

    12

    Version

    1.1.4

    License

    MIT

    Unpacked Size

    25.7 kB

    Total Files

    21

    Last publish

    Collaborators

    • julien.arlandis