Monocle API Client for JavaScript

Monocle is a schema-powered API router that focuses on consistency, flexibility and performance.

QuickStart

Getting started with Monocle is simple:

1. Add Angular and Monocle scripts to your page
2. Add monocle as a dependency to your Angular application.
3. Inject monocle and start making API calls!

// Add `monocle` as a dependency:varapp=angular.module('app',['monocle']);// Inject `monocle` to gain easy access to a Monocle-powered APIapp.service('Users',function(monocle){this.get=function(userId){returnmonocle.get('/users/'+userId,{props: ['userId','displayName','age']});};});

Configuration

The monocle client can be configured in your app's config phase.

// Configure the Monocle client:app.config(function(monocleProvider){// Set the base path for API calls.// All API calls will automatically be mounted onto this base path.monocleProvider.setBase('/api');// Set a custom timeout to be used by all requests (default: 30,000ms).monocleProvider.setTimeout(10000);// Set a custom header by value.monocleProvider.setHeader('x-custom-value','test-custom-value');// Set a custom header by providing a callback function.// The function will be called for each HTTP request to the Monocle server,// and its return value will be the value for the header.// If the function returns a promise, it will be resolved first.monocleProvider.setHeader('x-custom-callback',function(){return'test-custom-callback-'+Math.random();});// Set a custom header by providing a promise.// The resolved value will be used as the header value.monocleProvider.setHeader('x-custom-promise',Promise.resolve('test-custom-promise'));// Set a custom header by providing a function that returns a promise.// The resolved value will be used as the header value.monocleProvider.setHeader('x-custom-promise-callback',function(){returnPromise.resolve('test-custom-promise-callback');});});

The monocle node adapter can be configured in your app's config phase.

varmonocle=require('monocle-client-js');// Configure the Monocle Node Adapter:varnodeAdapter=newmonocle.nodeAdapter();// Set a custom timeout to be used by all requests.nodeAdapter.setTimeout(30000);// Set a custom header by value.nodeAdapter.setHeader('x-custom-value','custom_client_value');varmonocleProvider=newmonocle(nodeAdapter);// Set the host path for API calls.// All API calls will automatically be mounted onto this host path.monocleProvider.setHost('http://www.yourhost.com');// Set the base path for API calls.// All API calls will automatically be mounted onto this base path.monocleProvider.setBase('/api/v2');

To make a request with the node adapter or with the monocle client

// FOR GET//The second parameter takes an optional object where props or query can be passed inmonocleProvider.get('/endpoint',{props: PROPS,query: QUERY);//FOR POST, PUT, PATCH OR DELETE//The second parameter takes an optional object where the body of the request can be passed in//Note: Currently the node adapter does not support the body parameter to be passed inmonocleProvider.post('/endpoint',{body: {param: 'param1'});monocleProvider.patch('/endpoint',{body: {param: 'param1'});monocleProvider.put('/endpoint',{body: {param: 'param1'});monocleProvider.delete('/endpoint');//Examples:monocleProvider.get('/users/123',{props: ['name'],query: {new: false}});monocleProvider.post('/users/345',{body: {name : 'Mariane'}});monocleProvider.patch('/users/123',{body: {name : 'Mariane'}});monocleProvider.put('/users/123',{body: {name : 'Mariane'}});monocleProvider.delete('/users/123');//Deletes user 123