How to implement a ETAG header in a GraphQL API with NestJS
What is a ETag?
The ETag, or entity tag, is a HTTP response header serving as an identifier for a specific version of a resource. This mechanism allows caches to be more efficient and save bandwidth, as a web server or even backend services does not need to resend a full response if the content has not changed.
The ETag value is computed based on the requested resource. The method for generating ETag values isn't specified. Typically, the ETag value is a hash of the content, a hash of the last modification timestamp, or a revision number. For the current implementation, we will utilize the npm package etag to generate the ETag value based on the response content.
How it Works?
When a client requests a resource, a unique ETag is calculated based on the resource's content and appended to the ETag response header with the value of the current date and the Last-Modified header.
Upon subsequent requests from the client with a previously generated ETag, the server compares the client's ETag (sent in the If-None-Match header) with the ETag for the current version of the resource. If both values match, indicating no changes to the resource, the server responds with a 304 Not Modified status without a body, informing the client that the cached response remains valid (fresh).
Implementing ETag Headers in a NestJS GraphQL API
Implementing ETag in a GraphQL API may require additional effort due to GraphQL filters that execute just before the response is transmitted over the internet. These filters format the response content within a field called data, report errors on the errors field, validate the response against the requested query, and set the response code as 200.
Setup
The only necessary configuration is to disable the default behavior of an Express application with the ETag header. By default, Express (used by NestJS) generates an ETag for all GET HTTP requests. This can be disabled as follows:
app.getHttpAdapter().getInstance().set('etag', false);Apollo Server Plugin
Plugins are TypeScript (JavaScript) objects that implement one or more functions to respond to events. We will follow the process outlined in the NestJS documentation for a custom plugin (
import { Plugin } from '@nestjs/apollo';
import {
ApolloServerPlugin,
GraphQLRequestContextWillSendResponse,
GraphQLRequestListener,
} from '@apollo/server';
@Plugin()
export class EtagPlugin implements ApolloServerPlugin {
async requestDidStart(): Promise<GraphQLRequestListener<ApolloServerPlugin>> {
return {
willSendResponse: async (
requestContext: GraphQLRequestContextWillSendResponse<ApolloServerPlugin>,
) => {
const req = requestContext.request;
const res = requestContext.response;
//..
},
};
}
}The method requestDidStart is invoked once per request before parsing or validating the request. This hook can return an object containing more granular hooks. For instance, the willSendResponse hook is invoked when the initial response (including resolved fields) is ready to be sent.
Now we have all the necessary components to implement the ETag header on a GraphQL API. The steps are outlined below:
Generate ETags:
When a client requests a resource, calculate a unique ETag based on the resource's content and include the ETag in the GraphQL Response:
@Plugin()
export class EtagPluging implements ApolloServerPlugin {
async requestDidStart(): Promise<GraphQLRequestListener<ApolloServerPlugin>> {
return {
willSendResponse: async (
requestContext: GraphQLRequestContextWillSendResponse<ApolloServerPlugin>,
) => {
const req = requestContext.request;
const res = requestContext.response;
const responseEtag = etag(JSON.stringify(res)); //<-- etag npm package
res.http.headers.set('etag', responseEtag);
//....
},
};
}
}Handle Conditional Requests
@Plugin()
export class EtagPluging implements ApolloServerPlugin {
async requestDidStart(): Promise<GraphQLRequestListener<ApolloServerPlugin>> {
return {
willSendResponse: async (
requestContext: GraphQLRequestContextWillSendResponse<ApolloServerPlugin>,
) => {
const req = requestContext.request;
const res = requestContext.response;
const responseEtag = etag(JSON.stringify(res)); //<-- etag npm package
res.http.headers.set('etag', responseEtag);
const clientDate = req.http.headers.get('if-modified-since');
const clientEtag = req.http.headers.get('if-none-match');
const lastModified = this.getLastModified(responseEtag);
const currentDate = new Date().toUTCString();
if (lastModified) {
responseHeaders.set('last-modified', lastModified);
if (responseEtag === clientEtag && clientDate === lastModified) {
res.http.status = 304;
res.body = null;
}
} else {
this.setLastModified(responseEtag, currentDate);
responseHeaders.set('last-modified', currentDate);
}
},
};
}
}When a client makes subsequent requests for the same resource, it should include the received ETag in the If-None-Match header and the received last modification timestamp in the If-Modified-Since header.
When a request is received on the server with an If-None-Match header, the provided ETag should be compared with the current ETag of the resource. Similarly, when the If-Modified-Since header is received, the provided timestamp should be compared with the current last modification timestamp of the resource. If there is a match, the server should respond with a 304 Not Modified status.
Update Last-Modified on Resource Change:
To ensure clients receive the latest version of a resource, update its last modification timestamp whenever changes are made. The method for saving the last modified value is not defined and can be implemented in various ways, such as through caching or a database.
