# `$http` (service in module `ng` )

Improve this doc

## Description

The `$http` service is a core Angular service that facilitates communication with the remote HTTP servers via browser's XMLHttpRequest object or via JSONP.

For unit testing applications that use `$http` service, see $httpBackend mock.

For a higher level of abstraction, please check out the $resource service.

The $http API is based on the `deferred/promise APIs` exposed by the $q service. While for simple usage patters this doesn't matter much, for advanced usage, it is important to familiarize yourself with these apis and guarantees they provide.

### General usage

The `$http` service is a function which takes a single argument — a configuration object — that is used to generate an http request and returns a `promise` with two $http specific methods: `success` and `error`.

      $http({method: 'GET', url: '/someUrl'}).
        success(function(data, status, headers, config) {
          // this callback will be called asynchronously
          // when the response is available
        }).
        error(function(data, status, headers, config) {
          // called asynchronously if an error occurs
          // or server returns response with an error status.
        });

Since the returned value of calling the $http function is a Promise object, you can also use the `then` method to register callbacks, and these callbacks will receive a single argument – an object representing the response. See the api signature and type info below for more details.

A response status code that falls in the [200, 300) range is considered a success status and will result in the success callback being called. Note that if the response is a redirect, XMLHttpRequest will transparently follow it, meaning that the error callback will not be called for such responses.

### Shortcut methods

Since all invocation of the $http service require definition of the http method and url and POST and PUT requests require response body/data to be provided as well, shortcut methods were created to simplify using the api:

      $http.get('/someUrl').success(successCallback);
      $http.post('/someUrl', data).success(successCallback);

Complete list of shortcut methods:

- `$http.get`
- `$http.head`
- `$http.post`
- `$http.put`
- `$http.delete`
- `$http.jsonp`

### Setting HTTP Headers

The $http service will automatically add certain http headers to all requests. These defaults can be fully configured by accessing the `$httpProvider.defaults.headers` configuration object, which currently contains this default configuration:

- `$httpProvider.defaults.headers.common` (headers that are common for all requests):
  - `Accept: application/json, text/plain, * / *`
- `$httpProvider.defaults.headers.post`: (header defaults for HTTP POST requests)
  - `Content-Type: application/json`
- `$httpProvider.defaults.headers.put` (header defaults for HTTP PUT requests)
  - `Content-Type: application/json`

To add or overwrite these defaults, simply add or remove a property from this configuration objects. To add headers for an HTTP method other than POST or PUT, simply add a new object with name equal to the lower-cased http method name, e.g. `$httpProvider.defaults.headers.get['My-Header']='value'`.

Additionally, the defaults can be set at runtime via the `$http.defaults` object in a similar fashion as described above.

### Transforming Requests and Responses

Both requests and responses can be transformed using transform functions. By default, Angular applies these transformations:

Request transformations:

- if the `data` property of the request config object contains an object, serialize it into JSON format.

Response transformations:

- if XSRF prefix is detected, strip it (see Security Considerations section below)
- if json response is detected, deserialize it using a JSON parser

To globally augment or override the default transforms, modify the `$httpProvider.defaults.transformRequest` and `$httpProvider.defaults.transformResponse` properties of the `$httpProvider`. These properties are by default an array of transform functions, which allows you to `push` or `unshift` a new transformation function into the transformation chain. You can also decide to completely override any default transformations by assigning your transformation functions to these properties directly without the array wrapper.

Similarly, to locally override the request/response transforms, augment the `transformRequest` and/or `transformResponse` properties of the config object passed into `$http`.

### Caching

To enable caching set the configuration property `cache` to `true`. When the cache is enabled, `$http` stores the response from the server in local cache. Next time the response is served from the cache without sending a request to the server.

Note that even if the response is served from cache, delivery of the data is asynchronous in the same way that real requests are.

If there are multiple GET requests for the same url that should be cached using the same cache, but the cache is not populated yet, only one request to the server will be made and the remaining requests will be fulfilled using the response for the first request.

A custom default cache built with $cacheFactory can be provided in $http.defaults.cache. To skip it, set configuration property `cache` to `false`.

### Interceptors

Before you start creating interceptors, be sure to understand the `$q and deferred/promise APIs`.

For purposes of global error handling, authentication or any kind of synchronous or asynchronous pre-processing of request or postprocessing of responses, it is desirable to be able to intercept requests before they are handed to the server and responses before they are handed over to the application code that initiated these requests. The interceptors leverage the `promise APIs` to fulfil this need for both synchronous and asynchronous pre-processing.

The interceptors are service factories that are registered with the $httpProvider by adding them to the `$httpProvider.interceptors` array. The factory is called and injected with dependencies (if specified) and returns the interceptor.

There are two kinds of interceptors (and two kinds of rejection interceptors):

- `request`: interceptors get called with http `config` object. The function is free to modify the `config` or create a new one. The function needs to return the `config` directly or as a promise.
- `requestError`: interceptor gets called when a previous interceptor threw an error or resolved with a rejection.
- `response`: interceptors get called with http `response` object. The function is free to modify the `response` or create a new one. The function needs to return the `response` directly or as a promise.
- `responseError`: interceptor gets called when a previous interceptor threw an error or resolved with a rejection.

      // register the interceptor as a service
      $provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
        return {
          // optional method
          'request': function(config) {
            // do something on success
            return config || $q.when(config);
          },

          // optional method
         'requestError': function(rejection) {
            // do something on error
            if (canRecover(rejection)) {
              return responseOrNewPromise
            }
            return $q.reject(rejection);
          },

          // optional method
          'response': function(response) {
            // do something on success
            return response || $q.when(response);
          },

          // optional method
         'responseError': function(rejection) {
            // do something on error
            if (canRecover(rejection)) {
              return responseOrNewPromise
            }
            return $q.reject(rejection);
          };
        }
      });

      $httpProvider.interceptors.push('myHttpInterceptor');

      // register the interceptor via an anonymous factory
      $httpProvider.interceptors.push(function($q, dependency1, dependency2) {
        return {
         'request': function(config) {
             // same as above
          },
          'response': function(response) {
             // same as above
          }
      });

### Response interceptors (DEPRECATED)

Before you start creating interceptors, be sure to understand the `$q and deferred/promise APIs`.

For purposes of global error handling, authentication or any kind of synchronous or asynchronous preprocessing of received responses, it is desirable to be able to intercept responses for http requests before they are handed over to the application code that initiated these requests. The response interceptors leverage the `promise apis` to fulfil this need for both synchronous and asynchronous preprocessing.

The interceptors are service factories that are registered with the $httpProvider by adding them to the `$httpProvider.responseInterceptors` array. The factory is called and injected with dependencies (if specified) and returns the interceptor — a function that takes a `promise` and returns the original or a new promise.

      // register the interceptor as a service
      $provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
        return function(promise) {
          return promise.then(function(response) {
            // do something on success
          }, function(response) {
            // do something on error
            if (canRecover(response)) {
              return responseOrNewPromise
            }
            return $q.reject(response);
          });
        }
      });

      $httpProvider.responseInterceptors.push('myHttpInterceptor');

      // register the interceptor via an anonymous factory
      $httpProvider.responseInterceptors.push(function($q, dependency1, dependency2) {
        return function(promise) {
          // same as above
        }
      });

### Security Considerations

When designing web applications, consider security threats from:

- JSON Vulnerability
- XSRF

Both server and the client must cooperate in order to eliminate these threats. Angular comes pre-configured with strategies that address these issues, but for this to work backend server cooperation is required.

#### JSON Vulnerability Protection

A JSON Vulnerability allows third party web-site to turn your JSON resource URL into JSONP request under some conditions. To counter this your server can prefix all JSON requests with following string `")]}',\n"`. Angular will automatically strip the prefix before processing it as JSON.

For example if your server needs to return:

    ['one','two']

which is vulnerable to attack, your server can return:

    )]}',
    ['one','two']

Angular will strip the prefix, before processing the JSON.

#### Cross Site Request Forgery (XSRF) Protection

XSRF is a technique by which an unauthorized site can gain your user's private data. Angular provides following mechanism to counter XSRF. When performing XHR requests, the $http service reads a token from a cookie (by default, `XSRF-TOKEN`) and sets it as an HTTP header (`X-XSRF-TOKEN`). Since only JavaScript that runs on your domain could read the cookie, your server can be assured that the XHR came from JavaScript running on your domain. The header will not be set for cross-domain requests.

To take advantage of this, your server needs to set a token in a JavaScript readable session cookie called `XSRF-TOKEN` on first HTTP GET request. On subsequent non-GET requests the server can verify that the cookie matches `X-XSRF-TOKEN` HTTP header, and therefore be sure that only JavaScript running on your domain could have read the token. The token must be unique for each user and must be verifiable by the server (to prevent the JavaScript making up its own tokens). We recommend that the token is a digest of your site's authentication cookie with salt for added security.

The name of the headers can be specified using the xsrfHeaderName and xsrfCookieName properties of either $httpProvider.defaults, or the per-request config object.

## Dependencies

- `$httpBackend`
- `$browser`
- `$cacheFactory`
- `$rootScope`
- `$q`
- `$injector`

## Usage

    $http(config);

### Parameters

- `config – {object} –`

  Object describing the request to be made and how it should be processed. The object has following properties:

  - method – `{string}` – HTTP method (e.g. 'GET', 'POST', etc)
  - url – `{string}` – Absolute or relative URL of the resource that is being requested.
  - params – `{Object.<string|Object>}` – Map of strings or objects which will be turned to `?key1=value1&key2=value2` after the url. If the value is not a string, it will be JSONified.
  - data – `{string|Object}` – Data to be sent as the request message data.
  - headers – `{Object}` – Map of strings representing HTTP headers to send to the server.
  - xsrfHeaderName – `{string}` – Name of HTTP header to populate with the XSRF token.
  - xsrfCookieName – `{string}` – Name of cookie containing the XSRF token.
  - transformRequest – `{function(data, headersGetter)|Array.<function(data, headersGetter)>}` – transform function or an array of such functions. The transform function takes the http request body and headers and returns its transformed (typically serialized) version.
  - transformResponse – `{function(data, headersGetter)|Array.<function(data, headersGetter)>}` – transform function or an array of such functions. The transform function takes the http response body and headers and returns its transformed (typically deserialized) version.
  - cache – `{boolean|Cache}` – If true, a default $http cache will be used to cache the GET request, otherwise if a cache instance built with `$cacheFactory`, this cache will be used for caching.
  - timeout – `{number}` – timeout in milliseconds.
  - withCredentials - `{boolean}` - whether to to set the `withCredentials` flag on the XHR object. See requests with credentials for more information.
  - responseType - `{string}` - see requestType.

### Returns

`{HttpPromise}` –

Returns a `promise` object with the standard `then` method and two http specific methods: `success` and `error`. The `then` method takes two arguments a success and an error callback which will be called with a response object. The `success` and `error` methods take a single argument - a function that will be called when the request succeeds or fails respectively. The arguments passed into these functions are destructured representation of the response object passed into the `then` method. The response object has these properties:

- data – `{string|Object}` – The response body transformed with the transform functions.
- status – `{number}` – HTTP status code of the response.
- headers – `{function([headerName])}` – Header getter function.
- config – `{Object}` – The configuration object that was used to generate the request.

## Methods

- ### delete(url, config)

  Shortcut method to perform `DELETE` request

  #### Parameters

  - `url – {string} –`

    Relative or absolute URL specifying the destination of the request

  - `config(optional) – {Object=} –`

    Optional configuration object

  #### Returns

  `{HttpPromise}` –

  Future object

- ### get(url, config)

  Shortcut method to perform `GET` request

  #### Parameters

  - `url – {string} –`

    Relative or absolute URL specifying the destination of the request

  - `config(optional) – {Object=} –`

    Optional configuration object

  #### Returns

  `{HttpPromise}` –

  Future object

- ### head(url, config)

  Shortcut method to perform `HEAD` request

  #### Parameters

  - `url – {string} –`

    Relative or absolute URL specifying the destination of the request

  - `config(optional) – {Object=} –`

    Optional configuration object

  #### Returns

  `{HttpPromise}` –

  Future object

- ### jsonp(url, config)

  Shortcut method to perform `JSONP` request

  #### Parameters

  - `url – {string} –`

    Relative or absolute URL specifying the destination of the request. Should contain `JSON_CALLBACK` string.

  - `config(optional) – {Object=} –`

    Optional configuration object

  #### Returns

  `{HttpPromise}` –

  Future object

- ### post(url, data, config)

  Shortcut method to perform `POST` request

  #### Parameters

  - `url – {string} –`

    Relative or absolute URL specifying the destination of the request

  - `data – {*} –`

    Request content

  - `config(optional) – {Object=} –`

    Optional configuration object

  #### Returns

  `{HttpPromise}` –

  Future object

- ### put(url, data, config)

  Shortcut method to perform `PUT` request

  #### Parameters

  - `url – {string} –`

    Relative or absolute URL specifying the destination of the request

  - `data – {*} –`

    Request content

  - `config(optional) – {Object=} –`

    Optional configuration object

  #### Returns

  `{HttpPromise}` –

  Future object

## Properties

- ### defaults

  Runtime equivalent of the `$httpProvider.defaults` property. Allows configuration of default headers, withCredentials as well as request and response transformations.

  See "Setting HTTP Headers" and "Transforming Requests and Responses" sections above.

- ### pendingRequests

  Array of config objects for currently pending requests. This is primarily meant to be used for debugging purposes.

## Example

#### Source

#### Demo