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)
host
(String): the host of the HTTP API servicecredentialsMode
(String): one of the supportedcredentials
modes (omit
,same-origin
,include
), useful when working with HTTP Cookies. (optional)includeResponseHeaders
(Boolean): flag whether to include the response headers in the response, if omitted headers is omitted from responseincludeOriginalRequest
(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.maskSensitiveHeaderData
(Boolean): flag to mask sensitie data in the header. e.g. Authorization tokenenableRetry
(Boolean): flag to enable retry on network errors and500
response. (Default: false)retryConfig
(Object): Field required in the object listed belowmaxRetries
(Number): number of times to retry the request before failing the request. (Default: 50)retryDelay
(Number): amount of milliseconds to wait before retrying the next request. (Default: 200)backoff
(Boolean): activates exponential backoff. Recommended to prevent spamming of the server. (Default: true)maxDelay
(Number): The maximum duration (milliseconds) to wait before retrying, useful if the delay time grew exponentially more than reasonablefetch
(Function): Afetch
implementation which can be e.g.node-fetch
orunfetch
but also the native browserfetch
functiontimeout
(Number): Request/response timeout in ms. Must have globally available or passed inAbortController
AbortController
(AbortController): AnAbortController
instance. Could be abort-controller or 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
},
// Optional if not globally available
fetch,
}),
],
})
getErrorByCode(code)
Returns a custom error type given its status code.
Arguments
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')