readme.md

Matter In Motion. HTTP transport

Http transport extension for matter in motion framework

Usage

Transport installation instructions

Http transport adds root property to the app. It is just an express instance. Also, you can use app.use method to add a contract or any other express-compatible handler

Protocol

To use all advantages of HTTP protocol:

• GET
  1. Add call in the URL after API URL
  2. Add body as query string
• POST
  1. Add special MM header with call as JSON string
  2. Send body as string, number, boolean, or JSON string in request body

Put meta field in the standard Authorization: Bearer header.

HTTP request requires Accept and Content-Type headers to be set to application/json

The response will come as JSON string.

From the browser looks like this:

GET request:

const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/world.hello?name=John', true);
xhr.setRequestHeader('Authorization', 'Bearer ' + meta);
xhr.setRequestHeader('Accept', 'application/json');
xhr.send();
xhr.onload = function() {
  if (xhr.status === 200) {
    let msg = JSON.parse(xhr.responseText);
    console.log(msg);
  } else {
    console.log(xhr.status);
  }
}

POST request:

const xhr = new XMLHttpRequest();
xhr.open('POST', '/api', true);
xhr.setRequestHeader('MM', JSON.stringify({ call: 'world.hello' }) );
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('Accept', 'application/json');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.send(body);
xhr.onload = function() {
  if (xhr.status === 200) {
    let msg = JSON.parse(xhr.responseText);
    console.log(msg);
  } else {
    console.log(xhr.status);
  }
}

If you make POST request with content type set to multipart/* message will be marked as raw and request object will be passed into your API call method, so you can parse it any way you want.

OPTIONS request

This is similar to the POST but it will transform into question request and body will be ignored

Settings

Only port option is required. Everything else is optional.

• port — number. Accepting connections on the specified port
• host — string, '0.0.0.0'. Accepting connections on the specified hostname.
• limit — number, null. Limit content length for the api request
• encoding — string, 'utf8'. Encoding of the api request
• cors — defines the cross-origin HTTP request control. Every option adds corresponding http headers for preflight OPTIONS request and for actual request
  • allowOrigin — Recomended for the matter in motion protocol: '*',
  • allowMethods — Recomended for the matter in motion protocol: 'GET, POST, OPTIONS',
  • allowHeaders — Recomended for the matter in motion protocol: 'Authorization, Origin, Content-Type, Accept, MM',
  • maxAge — Recomended for the matter in motion protocol: 1728000
• tls — instead of http server will create https server, this should be the https server settings
• static — adds express.static static files handler. For more info look into official documentation
  • url — string, static url path
  • root — string, root directory from which the static assets are to be served
  • dotfiles — string, 'ignore'. Option for serving dotfiles. Possible values are “allow”, “deny”, and “ignore”
  • etag — boolean, true. Enable or disable etag generation
  • extensions — Sets file extension fallbacks: If a file is not found, search for files with the specified extensions and serve the first one found. Example: ['html', 'htm'].
  • index — string, 'index.html'. Sends the specified directory index file. Set to false to disable directory indexing.
  • lastModified — boolean, true. Set the Last-Modified header to the last modified date of the file on the OS.
  • maxAge — number, 0. Set the max-age property of the Cache-Control header in milliseconds or a string in ms format
  • redirect — boolean, true. Redirect to trailing “/” when the pathname is a directory.
  • setHeaders — function for setting HTTP headers to serve with the file.

Contract

The contract is a subclass of the express Router class that makes easy to add unit views.

To use as sub contract define handle method as express-like middleware

addView(path, view)

• path — path to add view to
• view — name of the view unit

addViews(obj)

Adds all views from obj:

this.addViews({
  '/?': 'index',
  '/contacts/?': 'contacts'
})

HTTP Methods

All the standart http methods (check the require('http').METHODS), except OPTIONS can be used as methods for your resource. To do that, you need to use uppercase method name as an API call declaration. Example:

  GET: function() {
    return {
      title: 'HTTP Test',
      description: 'returns the get request data',
      request: {},
      response: {},
      call: (auth, data) => data
    }
  }

And call it as GET /api/resource.

License: MIT

© velocityzen