path: root/3rdparty/js/angular-1.0.2/docs/partials/api/ng.$http.html

<h1><code ng:non-bindable="">$http</code>
<span class="hint">(service in module <code ng:non-bindable="">ng</code>
)</span>
</h1>
<div><h2 id="Description">Description</h2>
<div class="description"><p>The <code>$http</code> service is a core Angular service that facilitates communication with the remote
HTTP servers via browser's <a href="https://developer.mozilla.org/en/xmlhttprequest">XMLHttpRequest</a> object or via <a href="http://en.wikipedia.org/wiki/JSONP">JSONP</a>.</p>

<p>For unit testing applications that use <code>$http</code> service, see
<a href="api/ngMock.$httpBackend">$httpBackend mock</a>.</p>

<p>For a higher level of abstraction, please check out the <a href="api/ngResource.$resource">$resource</a> service.</p>

<p>The $http API is based on the <a href="api/ng.$q"><code>deferred/promise APIs</code></a> 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.</p>

<h3>General usage</h3>

<p>The <code>$http</code> service is a function which takes a single argument — a configuration object —
that is used to generate an http request and returns  a <a href="api/ng.$q"><code>promise</code></a>
with two $http specific methods: <code>success</code> and <code>error</code>.</p>

<pre class="prettyprint linenums">
  $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 status
      // code outside of the &lt;200, 400) range
    });
</pre>

<p>Since the returned value of calling the $http function is a Promise object, you can also use
the <code>then</code> 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.</p>

<h3>Shortcut methods</h3>

<p>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:</p>

<pre class="prettyprint linenums">
  $http.get('/someUrl').success(successCallback);
  $http.post('/someUrl', data).success(successCallback);
</pre>

<p>Complete list of shortcut methods:</p>

<ul>
<li><a href="api/ng.$http#get"><code>$http.get</code></a></li>
<li><a href="api/ng.$http#head"><code>$http.head</code></a></li>
<li><a href="api/ng.$http#post"><code>$http.post</code></a></li>
<li><a href="api/ng.$http#put"><code>$http.put</code></a></li>
<li><a href="api/ng.$http#delete"><code>$http.delete</code></a></li>
<li><a href="api/ng.$http#jsonp"><code>$http.jsonp</code></a></li>
</ul>

<h3>Setting HTTP Headers</h3>

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

<ul>
<li><code>$httpProvider.defaults.headers.common</code> (headers that are common for all requests):
<ul><li><code>Accept: application/json, text/plain, * / *</code></li>
<li><code>X-Requested-With: XMLHttpRequest</code></li></ul></li>
<li><code>$httpProvider.defaults.headers.post</code>: (header defaults for HTTP POST requests)
<ul><li><code>Content-Type: application/json</code></li></ul></li>
<li><code>$httpProvider.defaults.headers.put</code> (header defaults for HTTP PUT requests)
<ul><li><code>Content-Type: application/json</code></li></ul></li>
</ul>

<p>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.
<code>$httpProvider.defaults.headers.get['My-Header']='value'</code>.</p>

<p>Additionally, the defaults can be set at runtime via the <code>$http.defaults</code> object in a similar
fassion as described above.</p>

<h3>Transforming Requests and Responses</h3>

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

<p>Request transformations:</p>

<ul>
<li>if the <code>data</code> property of the request config object contains an object, serialize it into
JSON format.</li>
</ul>

<p>Response transformations:</p>

<ul>
<li>if XSRF prefix is detected, strip it (see Security Considerations section below)</li>
<li>if json response is detected, deserialize it using a JSON parser</li>
</ul>

<p>To override these transformation locally, specify transform functions as <code>transformRequest</code>
and/or <code>transformResponse</code> properties of the config object. To globally override the default
transforms, override the <code>$httpProvider.defaults.transformRequest</code> and
<code>$httpProvider.defaults.transformResponse</code> properties of the <code>$httpProvider</code>.</p>

<h3>Caching</h3>

<p>To enable caching set the configuration property <code>cache</code> to <code>true</code>. When the cache is
enabled, <code>$http</code> 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.</p>

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

<p>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.</p>

<h3>Response interceptors</h3>

<p>Before you start creating interceptors, be sure to understand the
<a href="api/ng.$q"><code>$q and deferred/promise APIs</code></a>.</p>

<p>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 <a href="api/ng.$q"><code>promise apis</code></a> to fulfil this need for both synchronous and asynchronous preprocessing.</p>

<p>The interceptors are service factories that are registered with the $httpProvider by
adding them to the <code>$httpProvider.responseInterceptors</code> array. The factory is called and
injected with dependencies (if specified) and returns the interceptor  — a function that
takes a <a href="api/ng.$q"><code>promise</code></a> and returns the original or a new promise.</p>

<pre class="prettyprint linenums">
  // 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
    }
  });
</pre>

<h3>Security Considerations</h3>

<p>When designing web applications, consider security threats from:</p>

<ul>
<li><a href="http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx">JSON Vulnerability</a></li>
<li><a href="http://en.wikipedia.org/wiki/Cross-site_request_forgery">XSRF</a></li>
</ul>

<p>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.</p>

<h4>JSON Vulnerability Protection</h4>

<p>A <a href="http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx">JSON Vulnerability</a> allows third party web-site to turn your JSON resource URL into
<a href="http://en.wikipedia.org/wiki/JSON#JSONP">JSONP</a> request under some conditions. To
counter this your server can prefix all JSON requests with following string <code>")]}',\n"</code>.
Angular will automatically strip the prefix before processing it as JSON.</p>

<p>For example if your server needs to return:
<pre class="prettyprint linenums">
['one','two']
</pre>

<p>which is vulnerable to attack, your server can return:
<pre class="prettyprint linenums">
)]}',
['one','two']
</pre>

<p>Angular will strip the prefix, before processing the JSON.</p>

<h4>Cross Site Request Forgery (XSRF) Protection</h4>

<p><a href="http://en.wikipedia.org/wiki/Cross-site_request_forgery">XSRF</a> 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
called <code>XSRF-TOKEN</code> and sets it as the HTTP header <code>X-XSRF-TOKEN</code>. 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.</p>

<p>To take advantage of this, your server needs to set a token in a JavaScript readable session
cookie called <code>XSRF-TOKEN</code> on first HTTP GET request. On subsequent non-GET requests the
server can verify that the cookie matches <code>X-XSRF-TOKEN</code> 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 <a href="http://en.wikipedia.org/wiki/Rainbow_table">salt for added security</a>.</p></div>
<h2 id="Dependencies">Dependencies</h2>
<ul class="dependencies"><li><code ng:non-bindable=""><a href="api/ng.$httpBacked">$httpBacked</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$browser">$browser</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$cacheFactory">$cacheFactory</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$rootScope">$rootScope</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$q">$q</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$injector">$injector</a></code>
</li>
</ul>
<h2 id="Usage">Usage</h2>
<div class="usage"><pre <