Send http(s) requests to a server

You can use $http in two ways, either as a function that accepts a configuration object, or use shorthand methods for common HTTP methods.

To use $http as a function, the config object needs to include the url and http method:

 $http({
     url: '/example',
     method: 'GET'
 });

For common http methods there are shorthand functions:

 $http.get('/url');
 $http.post('/example', { key: 'value' });

Both variations will return a Promise that resolves with the response from the server:

 $http.get('/example').then((response) => {
     console.log(response.data);
 });

The response object has the following properties:

 {
     data: {},
     //Data is the response body. If response content type is
     //'application/json' the response body will be JSON decoded and
     //the decoded object will be accessible in data
     status: 200, // http response code,
     headers: {
         'Content-Type': 'application/json'
     },// response http-headers,
     config: config, // config object send with request
     statusText: '200 Success' // http status text
 }

All shorthand-methods are documented separately and optionally accept the same config-object $http as a function accepts. Should the config object contain different data than the arguments for the shorthand method, then the arguments to the method take precedent:

 $http.get('/example', {}, { url: '/not-used' });
 //=> Sends request to '/example'

Configuration

The config object can have these keys:

 {
     pre: [],
     post: [],
     method: 'GET',
     url: '/example',
     data: {
         key: 'value'
     },
     params: {
         search: 'a search criteria'
     },
     headers: {
         'Content-Type': 'application/json'
     }
 }

Default settings can be set directly on $http and will be used for all future requests:

 mimeo.module('example', [])
     .run(['$http', ($http) => {
         $http.$config.headers['Authorization'] = 'Basic W@3jolb2'
     });

pre and post are callback-chains that can 1. Modify the config before a request (in case of pre) 2. Modify the response (in case of post)

To add callbacks simply push them to the array. It's up to you to manage the chain and add/remove functions from the array.

The function itself will receive the config for the request (for pre) or the response (for post). The functions in the chain will receive the return value from the previous function as input. The first function will receive the original config/response as input.

If you change values in the headers-object make sure not to override the headers object or if you do, to provide a 'Content-Type' header, otherwise requests might fail depending on the environment (unspecified content types should be avoided). Instead, simply add or modify headers on the existing headers object.

The data field is send as the request body and the params key is send as a query string in the url. The headers field allows you to set http headers for only this request, usually used to set a content type.

The default content type is 'application/json', so by default, data will be send as a JSON string to the server. If you want to send a browser-like form string (content type 'application/x-www-form-urlencoded') you have to set the content type in the headers field and data must be a string. It's up to you to build the form-urlencoded string.

Defaults

The default values $http uses can be changed and will be applied to every request. There are three configurable properties:

• $http.$host
• $http.$protocol
• $http.$config

$http.$host is the host that will be used for every request. By default, no host is used. For use in the browser this is fine, as the browser simply uses the current host. For use with NodeJS $http.$host has to be set as there is not default host. Setting the host for the browser will send all requests to the specified host, and not the current host. In that case the host has to support cross-origin HTTP requests.

$http.$protocol should be one of 'http' or 'https', depending on what your app uses.

$http.$config is merged into the config object passed to $http or one of the shorthand methods. The settings in the config object passed to $http or the shorthand method takes precedent:

 $http.$config.headers['Authorization'] = 'Basic F@L#B';
 $http.post('/example', { key: 'value' }, {
     headers: {
         'Authorization': 'None'
     }
 );
 //=> Will send 'None' as the 'Authorization' header.

An example changing all the available properties:

 mimeo.module('example', [])
     .run(['$http', ($http) => {
         $http.$host = 'http://www.example.com';
         $http.$protocol = 'https';
         $http.$config.headers['Authorization'] = 'Basic F@L#B'
     });