sdk-middleware-http

Middleware to send the actual HTTP request.

Install

Node.js

npm install --save @commercetools/sdk-middleware-http

Browser

<script src="https://unpkg.com/@commercetools/sdk-middleware-http/dist/commercetools-sdk-middleware-http.umd.min.js"></script>
<script>
  // global: CommercetoolsSdkMiddlewareHttp
</script>

createHttpMiddleware(options)

Creates a middleware to handle HTTP requests for the commercetools platform API.

The HTTP middleware can run in either a browser or Node.js environment. For Node.js environments it is important to either have a fetch implementation either globally available via e.g. isomorphic-fetch or to pass it in as an argument (see below) via e.g. node-fetch. In browsers without a native fetch implementation any well known fetch polyfill should be compatible with the middleware such as whatwg-fetch or unfetch.

Named arguments (options)

1. host (String): the host of the HTTP API service
2. credentialsMode (String): one of the supported credentials modes (omit, same-origin, include), useful when working with HTTP Cookies. (optional)
3. includeResponseHeaders (Boolean): flag whether to include the response headers in the response, if omitted headers is omitted from response
4. includeOriginalRequest (Boolean): flag whether to include the original request sent in the response. Can be useful if you want to see the final request being sent.
5. maskSensitiveHeaderData (Boolean): flag to mask sensitie data in the header. e.g. Authorization token
6. enableRetry (Boolean): flag to enable retry on network errors and 500 response. (Default: false)
7. retryConfig (Object): Field required in the object listed below
8. maxRetries (Number): number of times to retry the request before failing the request. (Default: 50)
9. retryDelay (Number): amount of milliseconds to wait before retrying the next request. (Default: 200)
10. backoff (Boolean): activates exponential backoff. Recommended to prevent spamming of the server. (Default: true)
11. maxDelay (Number): The maximum duration (milliseconds) to wait before retrying, useful if the delay time grew exponentially more than reasonable
12. retryOnAbort (Boolean): Configure the client to retry an aborted request or not. Defaults to false.
13. fetch (Function): A fetch implementation which can be e.g. node-fetch or unfetch but also the native browser fetch function
14. timeout (Number): Request/response timeout in ms. Must be globally available or passed in AbortController
15. abortController or getAbortController depending on what you chose to handle the timeout (abortController): This property accepts the AbortController instance. Could be abort-controller or a globally available one.

Retrying requests

This modules have a retrying ability incase of network failures or 503 response errors. To enable this behavior, pass the enableRetry flag in the options and also set the maximum number of retries (maxRetries) and amount of milliseconds to wait before retrying a request (retryDelay).

The repeater implements an exponential delay, meaning the wait time is not constant and it grows on every retry.

Token caching

The token is retrieved and cached upon the first request made by the client. Then, it gets refreshed when it expires. To utilize this, please make sure you use the same client instance and do not create new ones.

Usage example

import { createClient } from '@commercetools/sdk-client'
import { createHttpMiddleware } from '@commercetools/sdk-middleware-http'

const client = createClient({
  middlewares: [
    createHttpMiddleware({
      host: 'https://api.commercetools.com',
      includeResponseHeaders: true,
      includeOriginalRequest: true,
      maskSensitiveHeaderData: true,
      enableRetry: true,
      retryConfig: {
        maxRetries: 2,
        retryDelay: 300, //milliseconds
        maxDelay: 5000, //milliseconds
        retryOnAbort: false,
      },

      // Optional if not globally available
      timeout: 1000,
      fetch,
    }),
  ],
})

abortController | getAbortController

This is used to signal the retry module to retry the request in an event of a request timeout or service outage.

Usage example

// Use default options
const httpMiddleware = createHttpMiddleware({
  host: testHost,
  timeout: 1000, // time out after 1s
  fetch,
  abortController: new AbortController(),
})

Note however the slight difference in usage of the getAbortController property of the http middleware.

// Use default options
const httpMiddleware = createHttpMiddleware({
  host: testHost,
  timeout: 1000, // time out after 1s
  fetch,
  getAbortController: () => new AbortController(),
})

This is to ensure that a new instance of the AbortController is always created and is independent of each other. Unlike the former (abortController) which only creates a single abortController instance for the middleware, in this very case, if a single request times out, it will propagate to all other http requests that is using the AbortController instance. This is useful when a bunch of sent out requests needs to timeout if at least one within the bunch times out.

getErrorByCode(code)

Returns a custom error type given its status code.

Arguments

1. code (Number): the HTTP status code

Returns

(Error or undefined): A custom error type (e.g. BadRequest, Unauthorized) if the code matches, otherwise undefined.

Usage example

import { getErrorByCode } from '@commercetools/sdk-middleware-http'

const ErrorType = getErrorByCode(400)
const error = new ErrorType('Oops')