Change in default behavior for HTTP response headers

3 minute read

HTTP responses from API Builder automatically include headers for “server”, “content-md5”, and “etag” by default (unless explicitly configured to be disabled in http.headers configuration).

This behavior has been deprecated since API Builder - Unna release.

Beginning with the Unna release, the HTTP headers “server”, “content-md5”, and “etag” are regarded as legacy headers, and will not be sent unless explicitly enabled in http.headers configuration.

This will be the default behavior in all new services.

Why are we deprecating this feature

The “server” header is used to identify the product and version of the server, e.g. server: API Builder/4.93.0. It is excluded by default for security purposes. If included in HTTP responses, it can aid attackers in targeted exploits.

The “etag” (or entity tag) identifies a specific version of a resource that can be used for caching by the browser. The “etag” is computationally expensive and not necessary if clients do not use it. It is excluded by default for performance purposes.

The “content-md5” is a MD5 hash of the HTTP response, and is used to ensure the response body was not tampered with between the server and the client. It is computationally expensive and not necessary if clients do check the header or if more modern security mechanisms are in place (e.g. TLS). It is excluded by default for performance purposes.

How does this impact my service

All new services will have “server”, “content-md5”, and “etag” disabled by default.

Any existing services will continue to work as they previously did, though it is strongly recommended you upgrade the service. Note that the upgrade is a change of behavior that may impact existing clients that rely on “server”, “etag” or “content-md5”.

Upgrading existing services

Updates contain important changes to improve the performance, stability, and security of your services. Installing them ensures that your software continues to run safely and efficiently.

It is strongly recommended you upgrade API Builder to the latest version as well any data connectors you may have in your stack. This feature requires a minimum of:

• API Builder - Unna

After upgrading, the disableLegacyHeaders feature will not be active until you enable it. To enable it, add the following setting to your default.js file.

flags: {
    disableLegacyHeaders: true
}

Once disableLegacyHeaders is set to true, then “server”, “content-md5”, and “etag” are disabled by default, but the config.http.headers section can be used to explicitly enable or disable them.

If your service already has a config.http.headers, then your service is not impacted by this change, you can leave the configuration section as-is. Note that any header that is false can be deleted as they are now disabled by default.

If your service does not have a config.http.headers section, then you need to carefuly consider if your clients are impacted by “server”, “content-md5”, and “etag”, as they will not be sent by default. If clients of your service require “server”, “content-md5”, or “etag”, then you can individually enable them in your config.http.headers, e.g.:

http: {
  // This is the port the service will be bound to. Defaults to 8080.
  port: parseInt(process.env.PORT) || 8080,

  // When this is true, the service will no longer listen on requests over http.
  // Disabling http requires 'ssl' to be configured.
  disabled: false,

  // Controls certain header algorithms.
  headers: {
    etag: true
  }
},

If “server” is already set to true, you should consider disabling it (or deleting it) for security purposes.

For more detailed information on the configuration options, see Project configuration.

Once enabled, ensure any clients do not depend on the deprecated behavior.