POST requests

To use POST requests, you must define the request in the Model file in the JSON format. The definition entry is comprised of a path and body. The path contains the URL endpoint and the body used in requests, while the body defines documents and provides sample values. The driver then uses these sample values to define which data type to be used when executing a POST request.

An entry for a POST request with a parameterized or unparameterized path takes the following form for an entry defining two fields:

"<table_name>": {
          "#path": "<host_name>/<endpoint_path>",
          "#post": {
               "<field1>":"<value1>",
               "<field2>":"<value2>"
          }
     },

An entry for a POST request with parameters takes the following form:

"<table_name>": {
          "#path": "<host_name>/<endpoint_path>",
          "#post": {
               "<field1>":"<value1>",
               "<field2>":"<value2>"
          }
           "<column_name>":{
                  "#type":"<data_type>",
                  "<operator>"":"<uri_parameter>"
          }
     },

You can also map custom parameter values to a column using the #postParameter property. This allows for filtering in scenarios where complex parameter syntax is employed, such as using complicated JSON data or empty arrays. An entry for a POST request that filters using a custom parameter takes the following form:

"<table_name>": {
          "#path": "<host_name>/<endpoint_path>",
          "#post": {
               "<field1>":"<value1>",
               "<field2>":"<value2>"
          }
           "<column_name>":{
                  "#type":"<data_type>",
                  "#postParameter":"<merge_behavior>",
                  "#default":"<default_parameter>"
          }
     },

table_name

is the name of the relational table to which the driver maps the endpoint. For example, countries2.

host_name

(optional) is the protocol and host name components of the URL endpoint. For example, http://example.com. You can omit this value by specifying the host name using the ServerName property.

endpoint_path

is the path component of the URL endpoint. For example, country. This can be an unparameterized or parameterized path, a path that uses query parameters, or an array of paths. See "Query paths" for examples and more information.

field

is the field name of the field=value pair. For example, START_DATE.

value

is the sample value the driver uses to determine the data type to use when executing a POST to that document. For example, 2018-08-31.

column_name

specifies the name of the column against which you are using query parameters.

data_type

specifies the data type mapping for the corresponding column.

operator

specifies the property that corresponds to the query operator that you want to used to filter results. This value can be #eq, #lt, #gt, #le, #ge, #ne, or #in. See "Filtering and URI parameters" for details.

uri_property

specifies the name of the URI property to be filtered by the operator.

merge_behavior

specifies how the values of the column will be merged with the POST body. Valid values are:

• json: The value of the column is merged into the body as JSON.
• replace: The value of this column replaces all other POST parameters included in the POST body. This provides control over all of the POST body's parameters using a single set of properties.

default_parameter

(optional) specifies the name of the default parameter value to be filtered by the operator. If the default property is omitted, the value must be specified in the WHERE clause to filter by this column.

For example, the following demonstrates an entry for a POST request using an unparameterized request.

"countries2": {
          "#path": "http://example.com/country/",
          "#post": {
               "start_date":"2018-08-31",
               "end_date":"2018-09-01",
               "departments":"[engineering,marketing,sales]",
               "tags":"[blue,green,red]"
          }
     },

For example, the following demonstrates an entry for a POST request using a parameterized request.

"football": {
          "#path": "http://example.com/football/{team:Wildcats}",
          "#post": {
               "opponent":"Tigers",
               "date":"2018-2-2",
          }
     },

For example, the following demonstrates an entry for a POST request with parameters.

"incidents": {
          "#path": "https://www.example.com/safety/",
          "#post": {
               "departments":"accounting",
               "date":"2015-10-8",
               }
           "reported":{
                  "#type":"date",
                  "#eq":"reportedOn"
          }
     },

For example, the following demonstrates an entry for a POST request with custom parameters.

"incidents": {
          "#path": "https://www.example.com/issues/",
          "#post": {
               "id":"99-99999",
               "date":"2015-10-8",
               }
           "department":{
                  "#type":"VarChar",
                  "#postParameter":"json"
                  "#default": "{\"employee\": []}"
          }
     },