skip to main content
Input REST file syntax : HTTP response code processing
  

Try DataDirect Drivers Now

HTTP response code processing

The driver allows you to customize how HTTP response status codes are processed by the driver. This provides you with a method to define error responses for codes that are returned by the service, including subsequent driver actions and error messages. By using the #operation and #match properties, you can further limit the definition to apply only to responses for certain operations or for service responses that contain specific content, such as a specific error message.
If no #http entry is created to define how response codes are processed, the driver handles response codes according to the default actions in the following table. Note that if you supply your own #http entry, you must provide a definition for each response code that the service returns. Any code not explicitly defined in your entry will be returned as a failure.
Code
Action
200
OK
400
ZERO_ROWS
401
REAUTHENTICATE
404
ZERO_ROWS
429
RETRY_AFTER
503
RETRY_AFTER
An entry to define HTTP response code processing takes the following form for multiple definitions:
"#http":[
{
"#code":<code_number1>,
"#action":"<action>",
"#operation":"<operation>",
"#match":"<match_string>",
"#message":"<message>"
},
{
"#code":<code_number2>,
"#action":"<action>",
"#operation":"<operation>",
"#match":"<match_string>",
"#message":"<message>"
},
{
"#code":<code_number3>,
"#action":"<action>",
"#operation":"<operation>",
"#match":"<match_string>",
"#message":"<message>"
}
]
Important: The driver reads definitions in the order listed and uses the first one that matches the response being evaluated. Therefore, if you have multiple definitions for a single code response, it’s important to specify definitions with #match and #operation parameters before definitions without conditions. This helps the driver avoid using a definition that is designed to generally apply to a code before evaluating those with specific conditions.
code_number
is the numeric HTTP status code for which you want to define driver behavior. For example, 200, 401, 404, etc.
action
is the action the driver takes after the specified HTTP status code is returned and the values of the operation and match properties are determined to apply. A list of supported actions is described in the "Action Values" table.
operation
(optional) is the operation types to which you want to limit the response definition to apply. For example, if you only wanted the behavior defined in this entry to apply to instances when performing insert operations, set this value to Select. See the "Operation Values" table for a list of supported values and their definition.
match
(optional) is text used to limit the instances to which the response definition applies. When a value is provided for this property, the driver scans the first 512 bytes of the service response for the specified value. If it's detected, the driver determines that the behavior in the definition applies. For example, if you only wanted the behavior to apply when the response body contained the text "status":"error", you would specify the following:
"#match":"\"status\":\"error\"",
message
(optional) is the message text that you want the driver to return when encountering the specified status code. This is typically the error message you want returned to the user. You can specify this value as plain text or as a reference to a header of the server response. For example, to reference the "message" header in a service response, you would specify the following to display the text contained in the "message" header:
"#message":"{message}"
Table 24. Action Values
Value
Behavior
OK
The operation was successful without errors. In the case of executing a SELECT, zero or more rows were returned. No further action is taken.
ZERO_ROWS
Similar to OK, the operation was successful without errors; however, it does not try to find any rows in returned content. This can be used to sync the HTTP response behavior of the REST service to the expected SQL behavior. For example, when a URL is designed to fetch multiple objects, but there are no objects of that type to return, some services return a code 200 and an empty array. However, in that same scenario, other services might return a code 404 as an error to signify that no rows were returned. In those instances, you would want the code 404 returned using the ZERO_ROWS action, instead of as an error.
RESET
The driver reinitializes the connection as if it were the first statement
REAUTHENTICATE
The driver tries to authenticate again. This action can be used when an access token expires and a new one needs to be fetched.
RETRY_AFTER
The driver retries the query up to the number of times specified by the wsretrycount connection property. Note that if the response includes a Retry-After header, the driver will honor it.
RETRY_ONCE
The driver retries the operation once.
RETRY_GOOGLE
The driver retries the operation up to the number of times specified by the WSRetryCount property or 5 times, whichever is lesser, using the Google exponential backoff rules.
RETRY_AWS
The driver retries the operation up to number of times specified by the WSRetryCount property, using the Amazon Web Services exponential backoff rules as implemented in the getWaitTime() method.
RETRY_FIXED
The driver attempts to retry the operation up to the number of times specified by the WSRetryCount property. The default setting is 1 second.
FAIL
The operation should throw an exception. For example, a code 400 might mean that the service failed to comprehend the query.
Table 25. Operation Values
Value
Description
SELECT
All API calls involved in sampling endpoints or querying rows
LOGIN
API calls related to logging in, such as those for authenticating with OAuth2. Note that credentials are not automatically added to these requests.
API
API calls not related to data, such as those to retrieve schema or user settings.
GOODBYE
API calls related to logging out without overriding any result status actions like OK.