@commercetools-backend/express

@commercetools-backend/express

Zero-config HTTP server as Express.js to facilitate development.

This package is primarily built for HTTP servers used by Custom Applications and it provides a set of components to facilitate the development of the HTTP server.

Install

$ npm install --save @commercetools-backend/express

Session middleware

This Express.js middleware should be used to handle the authentication exchange between the server and the /proxy/forward-to endpoint of the Merchant Center API Gateway.

You can read more about the "Proxy to External API" concepts here.

const {
  createSessionMiddleware,
  CLOUD_IDENTIFIERS,
} = require('@commercetools-backend/express');

app.use(
  createSessionMiddleware({
    audience: 'https://my-api-server.com',
    issuer: CLOUD_IDENTIFIERS.GCP_EU,
  })
);
app.use((request, response, next) => {
  // `request.session` contains the useful information
});

Middleware options

• audience (string): The public-facing URL of your API server. The value should only contain the origin URL (protocol, hostname, port), the request path is inferred from the incoming request.

• issuer (string): Either a cloud identifier or a valid URL to the Merchant Center API Gateway. The cloud identifier maps to the Merchant Center API URL of the related cloud region.

  • gcp-au: https://mc-api.australia-southeast1.gcp.commercetools.com
  • gcp-eu: https://mc-api.europe-west1.gcp.commercetools.com
  • gcp-us: https://mc-api.us-central1.gcp.commercetools.com
  • aws-fra: https://mc-api.eu-central-1.aws.commercetools.com
  • aws-ohio: https://mc-api.us-east-2.aws.commercetools.com

• inferIssuer (boolean): Determines whether the issuer should be inferred from the custom request HTTP header x-mc-api-cloud-identifier which is sent by the Merchant Center API Gateway when forwarding the request. This might be useful in case the server is used in multiple regions.

Usage in Serverless Functions

If your HTTP server runs as a Serverless Function, the Express.js middleware should not be needed. Instead you can use the underlying function that does not require the next callback.

Example for Google Cloud Functions

const {
  createSessionAuthVerifier,
  CLOUD_IDENTIFIERS,
} = require('@commercetools-backend/express');

const sessionAuthVerifier = createSessionAuthVerifier({
  audience: 'https://my-api-server.com',
  issuer: CLOUD_IDENTIFIERS.GCP_EU,
});

exports.handler = async function (request, response) {
  try {
    await sessionAuthVerifier(request, response);
  } catch (error) {
    response.status(401).send(JSON.stringify({ message: 'Unauthorized' }));
    return;
  }

  // `request.session` contains the useful information
};

The same concept applies for serverless functions in other cloud providers.