ghostfolio/.agents/skills/angular-developer/references/http-client.md

HTTP communication with HttpClient and httpResource

Use Angular's HTTP APIs for backend communication so requests participate in dependency injection, interceptors, transfer cache, and security features.

Setup

In Angular v21 and later, HttpClient is available for injection by default. Add provideHttpClient(...) only when an app needs to configure HTTP features for a specific injector:

import {provideHttpClient, withInterceptors} from '@angular/common/http';

export const appConfig = {
  providers: [provideHttpClient(withInterceptors([authInterceptor]))],
};

• HttpClient uses the fetch backend by default.
• Use withXhr() only when upload progress events are required. Do not use withXhr() for server-side rendering.
• Use provideHttpClient(...) for feature configuration such as interceptors, XSRF options, XHR, or parent-request delegation.
• Calling provideHttpClient() with no features is not required for basic HTTP requests, but it configures the default HTTP feature set for that injector, including Angular's XSRF interceptor.
• Prefer provideHttpClient(...) over HttpClientModule for feature configuration, especially with multiple injectors.
• Use withRequestsMadeViaParent() when a child injector should add interceptors while still delegating to the parent HTTP chain.

HttpClient

Encapsulate backend calls in injectable services, not components:

import {HttpClient} from '@angular/common/http';
import {Service, inject} from '@angular/core';

@Service()
export class UserService {
  private readonly http = inject(HttpClient);

  getUser(id: string) {
    return this.http.get<User>(`/api/users/${id}`);
  }
}

Important rules:

• HttpClient requests are cold Observables. No request is sent until the Observable is subscribed to. Multiple subscriptions send multiple backend requests.
• Subscribe to mutation requests (post, put, patch, delete) so they execute.
• The generic type parameter is a type assertion only. Validate unknown backend data at runtime when the shape is not trusted.
• Use literal values for responseType and observe; if options are extracted, write values like responseType: 'text' as const.
• HttpHeaders and HttpParams are immutable; use the returned instance from .set() or .append().
• Fetch options such as timeout, cache, priority, mode, redirect, credentials, keepalive, referrer, referrerPolicy, and integrity are supported where the backend supports them. withCredentials: true overrides credentials.
• Handle failures through HttpErrorResponse. Network and timeout failures use status 0; backend failures use the server status code.
• Prefer the async pipe or toSignal for component reads so subscriptions are cleaned up.

Interceptors

Prefer functional interceptors configured with withInterceptors.

import {
  HttpHandlerFn,
  HttpRequest,
  provideHttpClient,
  withInterceptors,
} from '@angular/common/http';

export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  return next(req.clone({setHeaders: {Authorization: 'Bearer token'}}));
}

export const appConfig = {
  providers: [provideHttpClient(withInterceptors([authInterceptor]))],
};

• Interceptors run in the order listed.
• Request and response objects are mostly immutable; clone before changing them.
• Request and response bodies are not deeply immutable. Avoid in-place body mutation because retries can run the same interceptor again.
• Use inject() inside functional interceptors for services.
• Use HttpContextToken for per-request metadata that interceptors need but the backend should not receive.
• Use DI-based interceptors only for existing code, and enable them with withInterceptorsFromDi().

Security

• HttpClient strips the XSSI prefix from JSON responses when present.
• provideHttpClient() configures XSRF protection by default for mutating relative and same-origin requests. It reads the XSRF-TOKEN cookie and sends the X-XSRF-TOKEN header.
• The backend must set the XSRF cookie and verify the header. Customize names with withXsrfConfiguration(...); disable only deliberately with withNoXsrfProtection().

httpResource

Use httpResource to create an asynchronous derivation that fetches data over HTTP and exposes the result as reactive signals.

import {httpResource} from '@angular/common/http';
import {input} from '@angular/core';

export class UserProfile {
  readonly userId = input.required<string>();
  readonly user = httpResource(() => `/api/users/${this.userId()}`);
}

• httpResource is eager. It sends a request when its reactive request computation runs, not when an Observable is subscribed.
• When a dependency changes, it cancels the pending request and sends the next one.
• Return undefined from the request function to skip a backend request.
• Prefer httpResource for reads. Use HttpClient directly for mutations such as POST, PUT, PATCH, and DELETE.
• Guard value() reads with hasValue(); reading value() while the resource is in an error state throws.
• Use httpResource.text, httpResource.blob, or httpResource.arrayBuffer for non-JSON responses.
• Use the parse option to validate or transform responses with a runtime schema.
• Read headers(), statusCode(), and progress() when response metadata or download progress is needed. Set reportProgress: true for progress events.