From 939c8e8fac0487da12e56291d69c5199a8ed9a30 Mon Sep 17 00:00:00 2001
From: Igor Minar
Date: Tue, 10 Jan 2012 19:16:33 -0800
Subject: docs($http, $httpBackend): docs docs docs
---
src/service/http.js | 322 +++++++++++++++++++++++++++++++++++++++++----
src/service/httpBackend.js | 5 +-
2 files changed, 298 insertions(+), 29 deletions(-)
(limited to 'src/service')
diff --git a/src/service/http.js b/src/service/http.js
index e9c49ec2..f9a8d921 100644
--- a/src/service/http.js
+++ b/src/service/http.js
@@ -139,35 +139,314 @@ function $HttpProvider() {
* @requires $q
* @requires $injector
*
- * @param {object} config Object describing the request to be made and how it should be processed.
- * The object has following properties:
+ * @description
+ * The `$http` service is a core Angular service that is responsible for communication with the
+ * remote HTTP servers via browser's {@link https://developer.mozilla.org/en/xmlhttprequest
+ * XMLHttpRequest} object or via {@link http://en.wikipedia.org/wiki/JSONP JSONP}.
+ *
+ * For unit testing applications that use `$http` service, see
+ * {@link angular.module.ngMock.$httpBackend $httpBackend mock}.
+ *
+ * For a higher level of abstraction, please check out the {@link angular.module.ng.$resource
+ * $resource} service.
+ *
+ *
+ * # 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 {@link angular.module.ng.$q 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 status
+ * // code outside of the <200, 400) range
+ * });
+ *
+ *
+ * Since the returned value 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.
+ *
+ *
+ * # 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:
+ *
+ *
+ *
+ * Complete list of shortcut methods:
+ *
+ * - {@link angular.module.ng.$http#get $http.get}
+ * - {@link angular.module.ng.$http#head $http.head}
+ * - {@link angular.module.ng.$http#post $http.post}
+ * - {@link angular.module.ng.$http#put $http.put}
+ * - {@link angular.module.ng.$http#delete $http.delete}
+ * - {@link angular.module.ng.$http#jsonp $http.jsonp}
+ *
+ *
+ * # 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, * / *`
+ * - `X-Requested-With: XMLHttpRequest`
+ * - `$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'`.
+ *
+ *
+ * # Request / Response transformations
+ *
+ * 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
+ *
+ * These transformations can be overridden locally by specifying transform functions as
+ * `transformRequest` and/or `transformResponse` properties of the config object. To globally
+ * override the default transforms, override the `$httpProvider.defaults.transformRequest` and
+ * `$httpProvider.defaults.transformResponse` properties of the `$httpProvider`.
+ *
+ *
+ * # Caching
+ *
+ * You can enable caching by setting 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.
+ *
+ *
+ * # Response interceptors
+ *
+ * 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 {@link angular.module.ng.$q
+ * 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 {@link angular.module.ng.$q promise} and returns the original or a new promise.
+ *
+ * Before you start creating interceptors, be sure to understand the
+ * {@link angular.module.ng.$q $q and deferred/promise APIs}.
+ *
+ *
+ * // 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 your design needs to consider security threats from
+ * {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
+ * JSON Vulnerability} and {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery 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 {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
+ * JSON Vulnerability} allows third party web-site to turn your JSON resource URL into
+ * {@link http://en.wikipedia.org/wiki/JSON#JSONP 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
+ *
+ * {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery 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
+ * called `XSRF-TOKEN` and sets it as the 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.
+ *
+ * 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 {@link http://en.wikipedia.org/wiki/Rainbow_table salt for added security}.
+ *
+ *
+ * @param {object} config 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.
* - **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.
+ * - **transformRequest** – `{function(data, headersGetter)|Array.}` –
+ * 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.}` –
+ * 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.
+ * GET request, otherwise if a cache instance built with
+ * {@link angular.module.ng.$cacheFactory $cacheFactory}, this cache will be used for
+ * caching.
+ * - **timeout** – `{number}` – timeout in milliseconds.
*
- * @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:
+ * @returns {HttpPromise} Returns a {@link angular.module.ng.$q 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.
*
- * @property {Array.