periodicjs.core.protocols
Description
Core protocols is a component of periodicjs.core.controller that exposes a standard set of methods across different transport protcols with options for implementing different API strategies. With core protocols implementing a RESTful API for HTTP requests looks no different than standing up a JSONRPC API for websocket based communications.
Full Documentation
Usage (basic)
const express = ;const mongoose = ;const ProtocolInterface = ;const DBInterface = ;const ResponderInterface = ; //Connect to the DB and start a HTTP servermongoose;mongooseconnection;/* With a JSON responder requests will by default receive a JSON response unless it requires a view to be rendered Implemented RESTful routes GET localhost:3000/example => Get All POST localhost:3000/example => Create One GET localhost:3000/example/:id => Get One PUT localhost:3000/example/:id => Update One DELETE localhost:3000/example/:id => Remove One */
Usage (advanced)
//In this example assume that mongo is already connected and the HTTP server is already startedlet http_adapter = ProtocolInterface;//This implements a router specifically for the example model. The .dirname option specifies a view directory if your view files are not in one of the default directorieslet router = http_adapterapi;//Because this returns a router you must manually mount it on the applications main router this does however allow for more control over the pathServer;/* Once again the JSON responder will by default be used unless a view must be rendered. If .strict option is passed when constructing the protocol adapter or in the this.api.implement call or this.implement call all responses will come a JSON. Additionally, the JSON responder will be used if req.query.format = "json" Implemented RESTful routes GET localhost:3000/api/v1/example?format=json => Get All POST localhost:3000/api/v1/example?format=json => Create One GET localhost:3000/api/v1/example/:id?format=json => Get One PUT localhost:3000/api/v1/example/:id?format=json => Update One DELETE localhost:3000/api/v1/example/:id?format=json => Remove One */
adapter.implement vs. adapter.api.implement
//In this example we are again assuming that mongo is connected and the server is startedlet http_adapter = ProtocolInterface;/* There are two implement methods exposed by this constructed object the first is accessed by .implement and is a method for both implementing an API strategy and mounting whatever is generated from the implementation. */http_adapter;/* This method has two potential outcomes dependent on if the http_adapter.express property is an already running express server or the express module itself. Another key difference is that this .implement method only uses the .express property of the protocol adapter. Case 1 (express server): .implement() directly mounts routes on the application sets the .router property equal to the ._router property of the express application Case 2 (express module): .implement() creates an express router and mounts routes sets the .router property equal to the generated router must separately mount router to application main router Both defines http_adapter.controller[model_name] as the generated controller methods for model */let router = http_adapterapi;/* This method is similar to http_adapter.implement with the key difference being that it implements an API strategy given any router and model and returns the values so that they can be used outside of the ecosystem of the protocol adapter. As such this method can be passed an optional .router property and will mount routes on the provided router. Only when this option is not defined will this method use the http_adapter.express router. Optionally .router can also be set to false in which case no router will be created and only controller methods are returned. */console; /* { new, show, edit, index, remove, search, create, update, load, load_with_count, load_with_limit, paginate, router <- When options.router is not false }*/
Development
Make sure you have grunt installed
$ npm install -g grunt-cli jsdoc-to-markdown
For generating documentation
$ grunt doc$ jsdoc2md adapters/**/*.js api_adapters/**/*.js utility/**/*.js index.js > doc/api.md
Notes
- Check out https://github.com/typesettin/periodicjs for the full Periodic Documentation
Testing
$ npm i$ grunt test
Contributing
License
MIT