Hopiu/angular.js
1
0
Fork 0
mirror of https://github.com/Hopiu/angular.js.git synced 2026-04-02 22:40:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs($http): doc fixes suggested by Gina

Browse source
This commit is contained in:
Igor Minar 2012-01-19 12:39:05 -08:00
parent 7046d6053d
commit efe33a5e21
1 changed files with 26 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
src/service/http.js
View file

@ -144,8 +144,8 @@ function $HttpProvider() {
* @requires $injector * @requires $injector
* *
* @description * @description
* The `$http` service is a core Angular service that is responsible for communication with the * The `$http` service is a core Angular service that facilitates communication with the remote
* remote HTTP servers via browser's {@link https://developer.mozilla.org/en/xmlhttprequest * HTTP servers via browser's {@link https://developer.mozilla.org/en/xmlhttprequest
* XMLHttpRequest} object or via {@link http://en.wikipedia.org/wiki/JSONP JSONP}. * XMLHttpRequest} object or via {@link http://en.wikipedia.org/wiki/JSONP JSONP}.
* *
* For unit testing applications that use `$http` service, see * For unit testing applications that use `$http` service, see
@ -154,6 +154,10 @@ function $HttpProvider() {
* For a higher level of abstraction, please check out the {@link angular.module.ng.$resource * For a higher level of abstraction, please check out the {@link angular.module.ng.$resource
* $resource} service. * $resource} service.
* *
* The $http API is based on the {@link angular.module.ng.$q 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 * # General usage
* The `$http` service is a function which takes a single argument — a configuration object — * The `$http` service is a function which takes a single argument — a configuration object —
@ -173,9 +177,10 @@ function $HttpProvider() {
* }); * });
* </pre> * </pre>
* *
* Since the returned value is a Promise object, you can also use the `then` method to register * Since the returned value of calling the $http function is a Promise object, you can also use
* callbacks, and these callbacks will receive a single argument – an object representing the * the `then` method to register callbacks, and these callbacks will receive a single argument –
* response. See the api signature and type info below for more details. * an object representing the response. See the api signature and type info below for more
* details.
* *
* *
* # Shortcut methods * # Shortcut methods
@ -199,7 +204,7 @@ function $HttpProvider() {
* - {@link angular.module.ng.$http#jsonp $http.jsonp} * - {@link angular.module.ng.$http#jsonp $http.jsonp}
* *
* *
* # HTTP Headers * # Setting HTTP Headers
* *
* The $http service will automatically add certain http headers to all requests. These defaults * 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 * can be fully configured by accessing the `$httpProvider.defaults.headers` configuration
@ -219,7 +224,7 @@ function $HttpProvider() {
* `$httpProvider.defaults.headers.get['My-Header']='value'`. * `$httpProvider.defaults.headers.get['My-Header']='value'`.
* *
* *
* # Request / Response transformations * # Transforming Requests and Responses
* *
* Both requests and responses can be transformed using transform functions. By default, Angular * Both requests and responses can be transformed using transform functions. By default, Angular
* applies these transformations: * applies these transformations:
@ -234,16 +239,16 @@ function $HttpProvider() {
* - if XSRF prefix is detected, strip it (see Security Considerations section below) * - if XSRF prefix is detected, strip it (see Security Considerations section below)
* - if json response is detected, deserialize it using a JSON parser * - if json response is detected, deserialize it using a JSON parser
* *
* These transformations can be overridden locally by specifying transform functions as * To override these transformation locally, specify transform functions as `transformRequest`
* `transformRequest` and/or `transformResponse` properties of the config object. To globally * and/or `transformResponse` properties of the config object. To globally override the default
* override the default transforms, override the `$httpProvider.defaults.transformRequest` and * transforms, override the `$httpProvider.defaults.transformRequest` and
* `$httpProvider.defaults.transformResponse` properties of the `$httpProvider`. * `$httpProvider.defaults.transformResponse` properties of the `$httpProvider`.
* *
* *
* # Caching * # Caching
* *
* You can enable caching by setting the configuration property `cache` to `true`. When the * To enable caching set the configuration property `cache` to `true`. When the cache is
* cache is enabled, `$http` stores the response from the server in local cache. Next time the * 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. * 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 * Note that even if the response is served from cache, delivery of the data is asynchronous in
@ -256,6 +261,9 @@ function $HttpProvider() {
* *
* # Response interceptors * # Response interceptors
* *
* Before you start creating interceptors, be sure to understand the
* {@link angular.module.ng.$q $q and deferred/promise APIs}.
*
* For purposes of global error handling, authentication or any kind of synchronous or * 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 * 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 * responses for http requests before they are handed over to the application code that
@ -267,9 +275,6 @@ function $HttpProvider() {
* injected with dependencies (if specified) and returns the interceptor — a function that * 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. * 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}.
*
* <pre> * <pre>
* // register the interceptor as a service * // register the interceptor as a service
* $provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) { * $provide.factory('myHttpInterceptor', function($q, dependency1, dependency2) {
@ -300,9 +305,12 @@ function $HttpProvider() {
* *
* # Security Considerations * # Security Considerations
* *
* When designing web applications your design needs to consider security threats from * When designing web applications, 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}. * - {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
* JSON Vulnerability}
* - {@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 * 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 * pre-configured with strategies that address these issues, but for this to work backend server
* cooperation is required. * cooperation is required.