Dynamic REST Data Handling
This topic describes the ways in which Loftware Spectrum processes data sent through REST Requests to Dynamic REST Endpoints.
The Loftware Spectrum REST API supports both GET and POST requests.
The following types of data from a REST request are placed into the Data Map.
-
HTTP Headers
-
HTTP URL Parameters
-
HTTP: Body Data
Important: Previous to Loftware Spectrum version 4.6, body data was placed into the MAP according to the passed in header Content-Type. This allowed multiple data types to be passed in a single request. Starting with version 4.6, data is placed into the MAP according to the selected REST endpoint's Request Processor Type, regardless of the passed in Content-Type.
Existing dynamic endpoints will continue to function in the previous fashion if Auto-Detect Request Processor is selected for the endpoint.
Request Processor Types
The following table describes the types of body data that can be processed by Loftware Spectrum.
|
Data Type |
Description |
Processing |
|---|---|---|
|
text |
Content-Type starts with "text". For example, "text/html". |
The string value is placed onto the MAP as plain text using the REST Endpoint Request Key as the key (or "/data" if not specified). If the text happens to be a JSON string, it will still be placed as a string to the specified key in the MAP, and it will be up to the BR script to convert it to a JavaScript object if desired. |
|
json |
Content-Type starts with "application/json". |
The request body is parsed as JSON and placed into the MAP according to the structure using the REST Endpoint Request Key as the root node, or "/" if not specified. Important: REST client calls made to REST Endpoints configured for application/json should configure a Content-Type of application/json;charset=UTF-8. |
|
multipart |
Content-Type starts with "multipart/form-data". This can handle form data which can be text, or files, or both. |
Multipart data is placed onto the MAP using the REST Endpoint Request Key as the root node (or "/data" if not specified). Multipart data will be placed under this node according to the form-data key as either text or a Base64 encoded string (in the case of binary data) |
|
XML |
Content-Type starts with "application/xml". |
The request body is parsed as XML and placed into the MAP according to the XML structure, using the REST Endpoint Request Key as the root node, or "/" if not specified. Important: REST client calls made to REST Endpoints configured for application/xml should configure a Content-Type of application/xml;charset=UTF-8. |
|
binary |
MIME types: application/*, audio/*, font/*, Image/* video/* |
Anything not matching the above data types is treated as binary data and Base64 encoded before being added to the map. |
Request Data Handling
REST Request Data will be placed into the Data Map for the business rule as follows:
| DataMap Key | Description |
|---|---|
| / | Default location where JSON request data will be placed. That is when no Request Key is specified for the Dynamic REST Endpoint |
| / | Location where request parameters passed on the URL will be placed. For example: http://url...?id=10000034&name=fbrown |
| /data | Default location where non-JSON request data will be placed. That is when no Request Key is specified for the Dynamic REST Endpoint. |
| /headers | HTTP Request headers will be placed here |
| <REST Endpoint Request Key> | When a Request Key is specified for the Endpoint, this is where body data will be placed. |
Request Compression
Spectrum supports a compressed Request Body.
If the Request Header contains "Content-Encoding=gzip", Spectrum will first decompress the body before adding the contents to the DataMap to send to the business rule. The contents must be compressed, or the request will fail with an error.
Note: Gzip is the supported compression format.
Response Data Handling
REST Response Data must be placed into the Data Map by the business rule as follows:
| DataMap Key | Description |
|---|---|
| <REST Endpoint Response Key> | MAP location where Response Data should be placed by the Business Rule Script. This will be returned in the response body |
| /responseHeaders | Custom headers that the user wants added to the REST Response |
| /jserror | Error that occurred as the result of executing a javascript RPC call. If this value is populated, it will return a response of "500 Internal Server Error". |
Response Compression
Gzip compression of the response is supported. The request must specify an "Accept-Encoding" header that contains "Gzip".
Note: Certain API tools like Postman and Chrome, automatically add an Accept-Encoding of Gzip, even when you don't specify it. In this case, the response will be compressed because it sees the value in the header. Specify an invalid or blank Accept-Encoding in the request if you do not wish to compress the response.
more