diff --git a/goldens/public-api/common/http/index.md b/goldens/public-api/common/http/index.md index e4f5ba1f9f6..9609f27496e 100644 --- a/goldens/public-api/common/http/index.md +++ b/goldens/public-api/common/http/index.md @@ -1728,7 +1728,7 @@ export enum HttpEventType { User = 5 } -// @public (undocumented) +// @public export interface HttpFeature { // (undocumented) ɵkind: KindT; @@ -1736,7 +1736,7 @@ export interface HttpFeature { ɵproviders: Provider[]; } -// @public (undocumented) +// @public export enum HttpFeatureKind { // (undocumented) CustomXsrfConfiguration = 2, @@ -2162,25 +2162,25 @@ export class JsonpInterceptor { static ɵprov: i0.ɵɵInjectableDeclaration; } -// @public (undocumented) +// @public export function provideHttpClient(...features: HttpFeature[]): EnvironmentProviders; -// @public (undocumented) +// @public export function withInterceptors(interceptorFns: HttpInterceptorFn[]): HttpFeature; -// @public (undocumented) +// @public export function withJsonpSupport(): HttpFeature; -// @public (undocumented) +// @public export function withLegacyInterceptors(): HttpFeature; -// @public (undocumented) +// @public export function withNoXsrfProtection(): HttpFeature; -// @public (undocumented) +// @public export function withRequestsMadeViaParent(): HttpFeature; -// @public (undocumented) +// @public export function withXsrfConfiguration({ cookieName, headerName }: { cookieName?: string; headerName?: string; diff --git a/packages/common/http/src/interceptor.ts b/packages/common/http/src/interceptor.ts index 9b215784827..a73434571da 100644 --- a/packages/common/http/src/interceptor.ts +++ b/packages/common/http/src/interceptor.ts @@ -66,6 +66,10 @@ export interface HttpInterceptor { * This function should only be called within the scope of the request that's currently being * intercepted. Once that request is complete, this downstream handler function should not be * called. + * + * @publicApi + * + * @see [HTTP Guide](guide/http#intercepting-requests-and-responses) */ export type HttpHandlerFn = (req: HttpRequest) => Observable>; diff --git a/packages/common/http/src/provider.ts b/packages/common/http/src/provider.ts index b8d2b160ad6..0c1aa7aeec9 100644 --- a/packages/common/http/src/provider.ts +++ b/packages/common/http/src/provider.ts @@ -15,6 +15,11 @@ import {jsonpCallbackContext, JsonpCallbackContext, JsonpClientBackend, jsonpInt import {HttpXhrBackend} from './xhr'; import {HttpXsrfCookieExtractor, HttpXsrfTokenExtractor, XSRF_COOKIE_NAME, XSRF_ENABLED, XSRF_HEADER_NAME, xsrfInterceptorFn} from './xsrf'; +/** + * Identifies a particular kind of `HttpFeature`. + * + * @publicApi + */ export enum HttpFeatureKind { Interceptors, LegacyInterceptors, @@ -24,6 +29,11 @@ export enum HttpFeatureKind { RequestsMadeViaParent, } +/** + * A feature for use when configuring `provideHttpClient`. + * + * @publicApi + */ export interface HttpFeature { ɵkind: KindT; ɵproviders: Provider[]; @@ -37,7 +47,21 @@ function makeHttpFeature( }; } - +/** + * Configures Angular's `HttpClient` service to be available for injection. + * + * By default, `HttpClient` will be configured for injection with its default options for XSRF + * protection of outgoing requests. Additional configuration options can be provided by passing + * feature functions to `provideHttpClient`. For example, HTTP interceptors can be added using the + * `withInterceptors(...)` feature. + * + * @see withInterceptors + * @see withLegacyInterceptors + * @see withXsrfConfiguration + * @see withNoXsrfProtection + * @see withJsonpSupport + * @see withRequestsMadeViaParent + */ export function provideHttpClient(...features: HttpFeature[]): EnvironmentProviders { if (ngDevMode) { @@ -73,6 +97,14 @@ export function provideHttpClient(...features: HttpFeature[]): return makeEnvironmentProviders(providers); } +/** + * Adds one or more functional-style HTTP interceptors to the configuration of the `HttpClient` + * instance. + * + * @see HttpInterceptorFn + * @see provideHttpClient + * @publicApi + */ export function withInterceptors(interceptorFns: HttpInterceptorFn[]): HttpFeature { return makeHttpFeature(HttpFeatureKind.Interceptors, interceptorFns.map(interceptorFn => { @@ -86,6 +118,17 @@ export function withInterceptors(interceptorFns: HttpInterceptorFn[]): const LEGACY_INTERCEPTOR_FN = new InjectionToken('LEGACY_INTERCEPTOR_FN'); +/** + * Includes class-based interceptors configured using a multi-provider in the current injector into + * the configured `HttpClient` instance. + * + * Prefer `withInterceptors` and functional interceptors instead, as support for DI-provided + * interceptors may be phased out in a later release. + * + * @see HttpInterceptor + * @see HTTP_INTERCEPTORS + * @see provideHttpClient + */ export function withLegacyInterceptors(): HttpFeature { // Note: the legacy interceptor function is provided here via an intermediate token // (`LEGACY_INTERCEPTOR_FN`), using a pattern which guarantees that if these providers are @@ -105,6 +148,13 @@ export function withLegacyInterceptors(): HttpFeature { @@ -119,6 +169,13 @@ export function withXsrfConfiguration( return makeHttpFeature(HttpFeatureKind.CustomXsrfConfiguration, providers); } +/** + * Disables XSRF protection in the configuration of the current `HttpClient` instance. + * + * This feature is incompatible with the `withXsrfConfiguration` feature. + * + * @see provideHttpClient + */ export function withNoXsrfProtection(): HttpFeature { return makeHttpFeature(HttpFeatureKind.NoXsrfProtection, [ { @@ -128,6 +185,11 @@ export function withNoXsrfProtection(): HttpFeature { return makeHttpFeature(HttpFeatureKind.JsonpSupport, [ JsonpClientBackend, @@ -137,6 +199,23 @@ export function withJsonpSupport(): HttpFeature { } /** + * Configures the current `HttpClient` instance to make requests via the parent injector's + * `HttpClient` instead of directly. + * + * By default, `provideHttpClient` configures `HttpClient` in its injector to be an independent + * instance. For example, even if `HttpClient` is configured in the parent injector with + * one or more interceptors, they will not intercept requests made via this instance. + * + * With this option enabled, once the request has passed through the current injector's + * interceptors, it will be delegated to the parent injector's `HttpClient` chain instead of + * dispatched directly, and interceptors in the parent configuration will be applied to the request. + * + * If there are several `HttpClient` instances in the injector hierarchy, it's possible for + * `withRequestsMadeViaParent` to be used at multiple levels, which will cause the request to + * "bubble up" until either reaching the root level or an `HttpClient` which was not configured with + * this option. + * + * @see provideHttpClient * @developerPreview */ export function withRequestsMadeViaParent(): HttpFeature {