Script: Class dw.system.RESTResponseMgr

Class RESTResponseMgr

  • Object
    • dw.system.RESTResponseMgr

This class provides helper methods for creating REST error and success responses. It is mainly intended to be used to build Custom REST APIs. But, any controller implementation planning to provide REST-like responses can use these methods. If these methods are being used in the controllers, note that a few defaults like URL prefix for type in createError methods will correspond to Custom REST APIs.

Constructor Summary

RESTResponseMgr()

Method Summary

static createEmptySuccess(statusCode : Number) : RESTSuccessResponse

Constructs a new RESTSuccessResponse object.

static createError(statusCode : Number) : RESTErrorResponse

Constructs a new RESTErrorResponse object.

static createError(statusCode : Number, type : String) : RESTErrorResponse

Constructs a new RESTErrorResponse object.

static createError(statusCode : Number, type : String, title : String) : RESTErrorResponse

Constructs a new RESTErrorResponse object.

static createError(statusCode : Number, type : String, title : String, detail : String) : RESTErrorResponse

Constructs a new RESTErrorResponse object.

static createSuccess(body : Object, statusCode : Number) : RESTSuccessResponse

Constructs a new RESTSuccessResponse object.

static createSuccess(body : Object) : RESTSuccessResponse

Constructs a new RESTSuccessResponse object.

Methods inherited from class Object

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

Constructor Detail

RESTResponseMgr

publicRESTResponseMgr()

Method Detail

createEmptySuccess

static createEmptySuccess(statusCode : Number) : RESTSuccessResponse

Constructs a new RESTSuccessResponse object. This method is to be used in scenarios where response body is not expected (e.g. statusCode is 204).

Parameters:

statusCode - The http status code of the response. The statusCode parameter should conform to RFC standards for a success.

Returns:

A new RESTSuccessResponse object.

Throws:

IllegalArgumentException - If the statusCode is not in the (100..299) range.

createError

static createError(statusCode : Number) : RESTErrorResponse

Constructs a new RESTErrorResponse object. This method should be used when you have just the statusCode of the error and want the type of error to be inferred.

'type' of the error is inferred from the status code as follows:

  • 400 - bad-request
  • 401 - unauthorized
  • 403 - forbidden
  • 404 - resource-not-found
  • 409 - conflict
  • 412 - precondition-failed
  • 429 - too-many-requests
  • 500 - internal-server-error
  • default - about:blank

Parameters:

statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an error.

Returns:

A new RESTErrorResponse object.

Throws:

IllegalArgumentException - If the statusCode is not in the (400..599) range.

createError

static createError(statusCode : Number, type : String) : RESTErrorResponse

Constructs a new RESTErrorResponse object. This method should be used when you want to omit 'title' and 'detail' of the error. With this method, custom error codes and types apart from the standard ones can be constructed.

Parameters:

statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an error.

type - Type of the error according to RFC 9457. We enforce the following restrictions on top of the RFC:

  • If the provided type is not an absolute URL, it will be prepended with https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/.
  • Custom error types are not allowed to have SYSTEM error type prefix: https://api.commercecloud.salesforce.com/documentation/error/v1/errors/.

Returns:

A new RESTErrorResponse object.

Throws:

IllegalArgumentException - If the statusCode is not in the (400..599) range or if the error type is not a valid URI or conflicts with the SYSTEM error type namespace.

createError

static createError(statusCode : Number, type : String, title : String) : RESTErrorResponse

Constructs a new RESTErrorResponse object. This method should be used when you want to omit 'detail' of the error but want to have valid 'statusCode', 'type' and 'title'.

Parameters:

statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an error.

type - Type of the error according to RFC 9457. We enforce the following restrictions on top of the RFC:

  • If the provided type is not an absolute URL, it will be prepended with https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/.
  • Custom error types are not allowed to have SYSTEM error type prefix: https://api.commercecloud.salesforce.com/documentation/error/v1/errors/.

title - Human-readable summary of the error type.

Returns:

A new RESTErrorResponse object.

Throws:

IllegalArgumentException - If the statusCode is not in the (400..599) range or if the error type is not a valid URI or conflicts with SYSTEM error type namespace.

createError

static createError(statusCode : Number, type : String, title : String, detail : String) : RESTErrorResponse

Constructs a new RESTErrorResponse object. This method can be used to construct error responses with valid 'statusCode', 'type', 'title' and 'detail'. If you want to omit title or detail, you can pass in null.

Parameters:

statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an error.

type - Type of the error according to RFC 9457. We enforce the following restrictions on top of the RFC:

  • If the provided type is not an absolute URL, it will be prepended with https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/.
  • Custom error types are not allowed to have SYSTEM error type prefix: https://api.commercecloud.salesforce.com/documentation/error/v1/errors/.

title - Human-readable summary of the error type.

detail - Human-readable explanation of the specific occurrence of the error.

Returns:

A new RESTErrorResponse object.

Throws:

IllegalArgumentException - If the statusCode is not in the (400..599) range or if the error type is not a valid URI or conflicts with SYSTEM error type namespace.

createSuccess

static createSuccess(body : Object, statusCode : Number) : RESTSuccessResponse

Constructs a new RESTSuccessResponse object.

Parameters:

body - The body of the successful response. This should always be a valid JavaScript JSON object.

statusCode - The http status code of the response. The statusCode parameter should conform to RFC standards for a success.

Returns:

A new RESTSuccessResponse object.

Throws:

IllegalArgumentException - If the statusCode is not in the (100..299) range.

createSuccess

static createSuccess(body : Object) : RESTSuccessResponse

Constructs a new RESTSuccessResponse object. HTTP status code of the response will be defaulted to 200.

Parameters:

body - The body of the successful response. This should always be a valid JavaScript JSON object.

Returns:

A new RESTSuccessResponse object.