Response Wrapping
The NMS REST API can return JSON responses in a common envelope containing data and error fields. This optional response format helps consuming applications, such as Oracle Integration Cloud (OIC), process successful responses and server errors using the same top-level structure.
To request response wrapping, include the X-NMS-API-Wrap HTTP header in each request. For example:
X-NMS-API-Wrap: true
The presence of the header enables wrapping; its value is not evaluated. An empty value also enables wrapping. To receive the original response format, omit the header. Setting its value to false does not disable wrapping.
When the header is present, wrapping applies to responses with the media type application/json as follows:
• Successful responses (HTTP 2xx): data contains the original response payload and error is null.
• Server error responses (HTTP 5xx): data is null and error contains the original error payload.
The payload placed in data or error retains its original structure. A payload can be an object, an array, or another JSON value, depending on the operation. Wrapping does not add status, code, or message fields to the envelope.
For example, a successful JSON response with an empty array as its original payload is wrapped as:
{
"data": [],
"error": null
}
The following server error example illustrates an existing error payload inside the envelope. Error details depend on the failure:
{
"data": null,
"error": {
"identifier": "89879887-de93-4fe0-8365-e105dcbe1919",
"title": null,
"stackTrace": "",
"message": "Unexpected Exception",
"localizedMessage": "java.lang.RuntimeException: Unexpected Exception",
"className": "java.lang.RuntimeException"
}
}
Response wrapping preserves the HTTP status code except for HTTP 204 (No Content). When X-NMS-API-Wrap is present, an HTTP 204 response becomes HTTP 200 (OK) with an application/json envelope. If the original response has no payload, both data and error are null:
{
"data": null,
"error": null
}
Responses with other status codes, including HTTP 3xx and 4xx, and non-204 responses with other media types, such as binary images, are returned without this envelope.
Consuming applications must continue to inspect the HTTP status code and handle responses that are not wrapped. Including the header does not guarantee that every response has data and error fields.