HttpClient Service

Relevant source files

• goldens/public-api/common/http/errors.api.md
• packages/common/http/public_api.ts
• packages/common/http/src/backend.ts
• packages/common/http/src/client.ts
• packages/common/http/src/context.ts
• packages/common/http/src/errors.ts
• packages/common/http/src/fetch.ts
• packages/common/http/src/headers.ts
• packages/common/http/src/interceptor.ts
• packages/common/http/src/jsonp.ts
• packages/common/http/src/params.ts
• packages/common/http/src/provider.ts
• packages/common/http/src/request.ts
• packages/common/http/src/response.ts
• packages/common/http/src/xhr.ts
• packages/common/http/src/xsrf.ts
• packages/common/http/test/BUILD.bazel
• packages/common/http/test/client_spec.ts
• packages/common/http/test/fetch_spec.ts
• packages/common/http/test/headers_spec.ts
• packages/common/http/test/jsonp_mock.ts
• packages/common/http/test/jsonp_spec.ts
• packages/common/http/test/params_spec.ts
• packages/common/http/test/provider_spec.ts
• packages/common/http/test/request_spec.ts
• packages/common/http/test/response_spec.ts
• packages/common/http/test/xhr_mock.ts
• packages/common/http/test/xhr_spec.ts
• packages/common/http/test/xsrf_spec.ts
• packages/common/http/testing/src/backend.ts
• packages/common/http/testing/src/provider.ts
• packages/common/http/testing/src/request.ts
• packages/common/http/testing/test/BUILD.bazel
• packages/common/http/testing/test/request_spec.ts
• packages/common/upgrade/src/location_shim.ts
• packages/common/upgrade/test/BUILD.bazel
• packages/common/upgrade/test/upgrade.spec.ts
• packages/common/upgrade/test/upgrade_location_test_module.ts
• packages/core/src/application/tracing.ts
• packages/core/test/acceptance/tracing_spec.ts
• packages/examples/core/animation/ts/dsl/animation_example.ts

Purpose and Scope

The HttpClient Service provides Angular's primary API for making HTTP requests. It offers a simplified, RxJS-based interface for communicating with backend servers, supporting both traditional XHR and modern Fetch API backends. This document covers the HttpClient class, its backend implementations, request/response handling, and the reactive httpResource API.

For information about HTTP security features (XSRF, XSSI), see HTTP Security Features. For the Resource API patterns used by httpResource, see Resource and httpResource APIs.

---

Core Architecture

The HttpClient system follows a layered architecture where the HttpClient service delegates to backend implementations through the HttpHandler interface.

HttpClient System Architecture

Architecture Diagram: HttpClient component hierarchy

Sources: packages/common/http/src/client.ts121-122 packages/common/http/src/fetch.ts74-83 packages/common/http/src/xhr.ts108-113 packages/common/http/src/backend.ts13-17 packages/common/http/src/provider.ts117-132

The HttpClient creates HttpRequest objects and passes them through a chain of interceptors before reaching a backend implementation. The backend translates the request into native browser APIs (Fetch or XHR) and returns an Observable<HttpEvent>.

---

HttpClient Service API

The HttpClient class in packages/common/http/src/client.ts121-1200 provides HTTP methods as instance methods that return RxJS Observables.

Request Methods

Method	Purpose	Request Body
get()	Retrieve data	None
post()	Create resource	Required
put()	Update resource	Required
patch()	Partial update	Required
delete()	Remove resource	Optional
head()	Headers only	None
options()	Allowed methods	None
request()	Generic request	Optional

Sources: packages/common/http/src/client.ts124-1200

Method Signatures and Overloads

Diagram: HttpClient method overload resolution

Each method has multiple overloads that vary based on:

• observe: Controls return type ('body', 'response', or 'events') packages/common/http/src/client.ts27
• responseType: Determines how to parse the response body packages/common/http/src/request.ts100

Sources: packages/common/http/src/client.ts142-250 packages/common/http/src/request.ts109-141

Request Options

Sources: packages/common/http/src/request.ts109-141 packages/common/http/src/client.ts25-31

---

Backend Implementations

Angular provides two backend implementations that translate HttpRequest objects into native browser APIs.

FetchBackend vs HttpXhrBackend

Feature	FetchBackend	HttpXhrBackend
Browser API	fetch()	XMLHttpRequest
File location	packages/common/http/src/fetch.ts74	packages/common/http/src/xhr.ts108
Upload progress	❌ Not supported fetch.ts39	✅ Supported xhr.ts35-36
Modern options	✅ Full support	⚠️ Limited support xhr.ts44-98
Node.js support	✅ v18+ fetch.ts67	❌ Browser only
SSR recommended	✅ Yes provider.ts78-81	❌ No

FetchBackend Implementation

Diagram: FetchBackend request processing flow

The FetchBackend in packages/common/http/src/fetch.ts74-400:

1. Creates an AbortController for cancellation packages/common/http/src/fetch.ts86
2. Calls fetchImpl (defaults to globalThis.fetch) packages/common/http/src/fetch.ts125-127
3. Reads the response body as a ReadableStream packages/common/http/src/fetch.ts163
4. Emits progress events if reportDownloadProgress: true packages/common/http/src/fetch.ts159-161
5. Concatenates chunks and parses based on responseType packages/common/http/src/fetch.ts320-352

Key implementation details:

• Runs outside Angular zone to avoid excessive change detection packages/common/http/src/fetch.ts125-127
• Handles XSSI prefix stripping for JSON responses packages/common/http/src/fetch.ts37-329
• Checks destroyRef.destroyed to prevent unnecessary work packages/common/http/src/fetch.ts198-200

Sources: packages/common/http/src/fetch.ts74-400

HttpXhrBackend Implementation

Diagram: HttpXhrBackend request processing

The HttpXhrBackend in packages/common/http/src/xhr.ts108-444:

1. Validates XHR compatibility for modern options packages/common/http/src/xhr.ts44-98
2. Opens XHR connection with method and URL packages/common/http/src/xhr.ts159
3. Sets headers, including default Accept and Content-Type packages/common/http/src/xhr.ts165-179
4. Registers event listeners for load, error, timeout, progress packages/common/http/src/xhr.ts233-414
5. Sends the serialized request body packages/common/http/src/xhr.ts417

Notable features:

• Memoizes HttpHeaderResponse to avoid duplicate parsing packages/common/http/src/xhr.ts206-227
• Handles JSON parsing with XSSI prefix removal packages/common/http/src/xhr.ts258-281
• Supports upload and download progress events packages/common/http/src/xhr.ts349-414

Sources: packages/common/http/src/xhr.ts108-444

---

Request and Response Model

HttpRequest

The HttpRequest<T> class in packages/common/http/src/request.ts153-700 represents an immutable HTTP request.

Key Properties:

Property	Type	Description
method	string	HTTP method (GET, POST, etc.)
url	string	Request URL without query params
urlWithParams	string	Full URL with query string
headers	HttpHeaders	Request headers
body	T | null	Request body
params	HttpParams	URL query parameters
responseType	HttpResponseType	Expected response format
reportDownloadProgress	boolean	Enable download progress events
withCredentials	boolean	Send cookies/auth
context	HttpContext	Request metadata

Sources: packages/common/http/src/request.ts153-400

---

Headers and Parameters

HttpHeaders

The HttpHeaders class in packages/common/http/src/headers.ts provides immutable header management.

Implementation Details:

• Case-insensitive header name storage.
• Supports raw \n-separated header strings.
• Compatible with browser Headers API.

Sources: packages/common/http/src/headers.ts24-290

HttpParams

The HttpParams class in packages/common/http/src/params.ts159-420 handles URL query parameters.

Sources: packages/common/http/src/params.ts159-420

---

HTTP Interceptors

Interceptors allow request/response transformation and side effects.

Interceptor Architecture

Diagram: HTTP interceptor chain execution

Sources: packages/common/http/src/interceptor.ts126-146 packages/common/http/src/backend.ts20-50

Interceptor Interface

Sources: packages/common/http/src/interceptor.ts126-129

Registration

Interceptors are registered via the provideHttpClient function using withInterceptors:

Sources: packages/common/http/src/provider.ts149-162

---

Configuration and Providers

Provider Functions

Function	Purpose
provideHttpClient()	Configure HttpClient with features provider.ts99
withXhr()	Use HttpXhrBackend provider.ts316
withInterceptors()	Register functional interceptors provider.ts149
withInterceptorsFromDi()	Use DI-based interceptors provider.ts179
withJsonpSupport()	Enable JSONP requests provider.ts249
withNoXsrfProtection()	Disable XSRF protection provider.ts230
withXsrfConfiguration()	Configure XSRF names provider.ts205

Sources: packages/common/http/src/provider.ts99-325

---

Performance Considerations

Change Detection Impact

Both backends run network operations outside Angular's zone to minimize change detection cycles:

• FetchBackend: Executes fetch() in NgZone.runOutsideAngular() packages/common/http/src/fetch.ts125-127
• HttpXhrBackend: Uses TracingService to propagate context without triggering unnecessary cycles packages/common/http/src/xhr.ts109-117

Sources: packages/common/http/src/fetch.ts125-127 packages/common/http/src/xhr.ts109-117