Angular HttpInterceptor: A Pipeline for API Requests

Why it exists

Without interceptors, logic for tasks like adding authentication headers or logging API calls must be repeated in every service that makes an HTTP request. This leads to code duplication and makes maintenance difficult. Interceptors solve this by providing a single, centralized place to handle logic that applies to all (or most) HTTP traffic.

The mental model

Think of HttpInterceptors as a series of customs agents forming a pipeline. When you make an API call, the request object travels through each agent (interceptor) in the chain. Each agent can inspect it, add something to it (like a header), or even deny it. After hitting the network, the server's response travels back through the same pipeline in reverse, giving you a chance to inspect or transform it before it reaches your application code.

How it works

An interceptor is a function that receives the outgoing HttpRequest and a next function. You perform your logic and then call next(req) to pass the request to the next interceptor in the chain, or to the backend if it's the last one. To modify a request, you must clone it first (e.g., req.clone({ setHeaders: ... })) because requests are immutable. You can also handle responses by using RxJS operators like pipe() on the Observable returned by next(req). Interceptors are registered in your application's providers using provideHttpClient(withInterceptors([myInterceptor])).

When to use it

Use interceptors for cross-cutting concerns that apply globally to your HTTP requests. Common patterns include: first, adding authentication tokens to headers; second, logging request and response details; third, caching responses to prevent redundant calls; fourth, implementing automatic retries for failed requests; and fifth, showing and hiding a global loading spinner.

When not to use it

Avoid using interceptors for business logic that is specific to a single component or feature. If a particular transformation or error handling strategy only applies to one API endpoint, it's better to handle it directly in the service that calls that endpoint. Using an interceptor for it would add unnecessary overhead to every other request in the application.

One canonical example

Adding a JWT authentication token to every outgoing request. The interceptor checks if a token exists in local storage. If it does, it clones the original request and adds an Authorization header with the token before passing it along the chain. This ensures every API call is authenticated without any service needing to know the implementation details.