What are Angular HTTP interceptors anyway?

Sometimes it takes more time or words to describe a concept in natural language, than to express it in code. Angular’s HTTP interceptors are such an example. The implementation is about half the size (about 30 lines of code at the time of writing) of the documentation (80 lines). Understanding the code behind frameworks’ features is often desirable as it improves understanding of language concepts (Promises in the case) as well as use cases for frameworks’ features.

In this article I am presenting the code that is driving Angular’s HTTP interceptor feature. You will learn how easy it is to look at Angular’s codebase, how versatile Promises are and we will look back at a common cross-cutting concern which is handled with HTTP interceptors.

Interceptors, a short reminder

Angular’s HTTP interceptors can be used to pre- and postprocess HTTP requests. Preprocessing happens before requests are executed. This can be used to change request configurations. Postprocessing happens once responses have been received. Responses can be transformed via postprocessing. Global error handling, authentication, loading animations and many more cross-cutting concerns can be implemented with HTTP interceptors. The following listing shows how a request (preprocessing) and response (postprocessing) interceptor can be used.

1const module = angular.module('interceptorTest', []);
2 
3module.config($httpProvider => {
4  $httpProvider.interceptors.push(
5    createInterceptor.bind(null, 'A'),
6    createInterceptor.bind(null, 'B')
7  );
8});
9 
10module.run($http => {
11  $http.get('https://api.github.com')
12  .then(response =>; console.log('Response handler'));
13});
14 
15angular.bootstrap(document.documentElement, [module.name]);
16 
17function createInterceptor(id) {
18  return {
19    request(config) {
20      console.log(`Interceptor ${id}: Request`);
21      return config;
22    },
23 
24    response(response) {
25      console.log(`Interceptor ${id}: Response`);
26      return response;
27    }
28  };
29}
30 
31// Generates the following output:
32// Interceptor A: Request
33// Interceptor B: Request
34// Interceptor B: Response
35// Interceptor A: Response
36// Response handler

Interceptors are registered with the $httpProvider by adding them to the $httpProvider.interceptors array. Interceptors execute in the order in which they appear in the aforementioned array, during the request phase. For the response phase, they are executed in reverse order. The following image illustrates the process and should help understand the reverse order part.

Looking at the source

Angular makes it easy to inspect the framework’s sources. The framework’s documentation is generated from the sources and every API documentation page contains a reference to the sources. A click on the View Source button in the top right corner sends you right to the source code on GitHub.

As mentioned in the introduction, the interceptor source code is fairly short. This is due to the fact that the interceptors are based on Promises. Promises are responsible for the complicated mechanism of config (preprocess) and response (postprocess) transformation orchestration. An example for such a transformation is a rejection handler which falls back to cached values when requests fail. For reference, this is the source code at the time of writing.

1// Source: https://github.com/angular/angular.js/blob/3fd48742b0fecbc470c44b465ba90786bda87451/src/ng/http.js#L794-L812
2var chain = [serverRequest, undefined];
3var promise = $q.when(config);
4 
5// apply interceptors
6forEach(reversedInterceptors, function(interceptor) {
7  if (interceptor.request || interceptor.requestError) {
8    chain.unshift(interceptor.request, interceptor.requestError);
9  }
10  if (interceptor.response || interceptor.responseError) {
11    chain.push(interceptor.response, interceptor.responseError);
12  }
13});
14 
15while (chain.length) {
16  var thenFn = chain.shift();
17  var rejectFn = chain.shift();
18 
19  promise = promise.then(thenFn, rejectFn);
20}

As you can see, request interceptors are chained together in the form of Promise transformations via then(onFulfilled, onRejected). This has interesting implications.

1. Response error interceptors can be used to resolve errors before the caller gets a chance to inspect the request’s result. This means that fallbacks can be implemented in a transparent way.
2. Because there are request and response interceptors that are capable of transforming config and response objects, the $http request config can be extended with domain specific attributes that are translated to standard HTTP headers.
3. Generic error handling is hard to get right. While every error could be caught, logged and the user informed, this is often not sufficient from a usability point of view. Some HTTP errors are expected and handled by userland code in Angular services, while others are unexpected and not handled. Angular’s interceptors concept does not provide native means to differentiate between expected and unexpected errors.

Conclusion

Angular’s HTTP interceptors are a fine example for the benefits of reading source code. It also shows the strength of Promises and how versatile they are. At the same time a closer look reveals that we need to put more energy into global error handling. A solution to take care of unhandled rejected Promises would need to exist to implement global error handling properly. The Q Promise library has something like this on the global Q object (API ). Angular’s version of Q unfortunately does not contain this feature.