Representations¶
The RESTful Web service can represent the data of the views in three formats:
By default, the RESTful Web service returns the data represented in
HTML, but clients can choose another representation (XML or JSON) by
either sending the appropriate Accept
header in the HTTP request or
by including the $format
parameter in the URL to invoke the Web
service (see the possible values of the $format
parameter in the table
Parameters supported by the Denodo RESTful Web service and published
REST Web services of the section Parameters of the RESTful Web Service).
The RESTful Web service returns the default representation (HTML) when
the request neither includes the Accept
HTTP header, nor it has the
$format
parameter in the URL. In addition, when the Accept
header contains several media types, the service returns HTML if the
media types text/html
or application/xhtml+xml
are present in
this header. However, if in the Accept
header, text/html
or
application/xhtml+xml
have a quality factor lower than 1, it will
return the representation with the highest quality factor (see the
example below)
The following table lists what will be the output of the RESTful Web service depending on the value of the Accept HTTP header of the request.
Accept HTTP Header of the Request |
Output Representation |
---|---|
text/html |
HTML |
application/xhtml+xml |
HTML |
application/xml |
XML |
application/json |
JSON |
application/json, application/xml, text/html |
HTML Although it is not the first media type in the list, it is the default one. |
application/xhtml+xml;q=0.9,applicat ion/json |
JSON Because the default representation (HTML) has a quality factor lower than the other supported representation. |
application/json;q=0.2,application/x ml;q=0.1 |
JSON Because the default representation (XML) has a quality factor lower than the other supported representation. |
application/rss+xml |
The service returns the HTTP error 406 Not Acceptable because the media type is only supported in appropriately configured REST Web services. |
The value of the parameter $format
overrides the value of the
Accept
HTTP header. For example, if a request contains the parameter
$format=json
and the value of the Accept
HTTP header is
text/html
, the Service will return the JSON representation of the
data.
XML Representation¶
When a client selects the XML representation, the Service returns an XML document.
To select this representation, clients have to add the Accept
header
application/xml
to the HTTP request or add the $format=XML
parameter to the URL (e.g.
http://localhost:9090/denodo-restfulws/admin/views/customer?$format=XML
).
The following are some general remarks about the XML representations:
We reuse the link element from the ATOM specification (Atom Syndication Format) to represent links.
The value self for the
rel
attribute of a link has the standard meanings defined by IANA (http://www.iana.org/assignments/link-relations/link-relations.xml). That is, the link provides an identifier for the parent element.The values
prev
andnext
have the standard meanings defined by IANA. That is, they are used for accessing the previous and next pagination intervals.When there is not a standard identifier for the relation represented by a certain link, we use Denodo-defined URIs to specify the semantics of the relation.
For instance, the value
http://www.denodo.com/restful/rels/viewSchema
identifies a link that allows accessing the schema of a certain view.
XML Representation of a Database¶
The figure below shows an example of the XML
representation of the database support
.
The URL to retrieve this document is something like this:
http://localhost:9090/denodo-restfulws/support?$format=XML
For each view of the database, there is a view-metadata
element,
which contains the following information:
A link to obtain the
view-metadata
element itself.A link to access the schema of the view, formatted in XML Schema.
A link to obtain the content of the view.
A link to obtain the associations of the view.
<?xml version="1.0" encoding="UTF-8"?>
<db name="support" xmlns="http://www.denodo.com/restful" xmlns:atom="http://www.w3.org/2005/Atom">
<description>Customers support database</description>
<view-metadata name="customer">
<description>Acme customers</description>
<atom:link rel="self"
href="http://localhost:9090/denodo-restfulws/support/views/customer/$metadata" />
<atom:link rel="http://www.denodo.com/restful/rels/viewSchema"
title="View Schema"
href="views/customer/$schema" />
<atom:link
rel="http://www.denodo.com/restful/rels/viewElements"
title="View Elements" href="views/customer"/>
<atom:link
rel="http://www.denodo.com/restful/rels/viewAssociations"
title="View Associations"
href="views/customer/$associations "/>
</view-metadata>
<view-metadata name="order">
<description>Acme's orders database</description>
<atom:link rel="self"
href="http://localhost:9090/denodo-restfulws/support/views/order/$metadata" />
<atom:link
rel="http://www.denodo.com/restful/rels/viewSchema"
title="View Schema"
href="views/order/$schema" />
<atom:link
rel="http://www.denodo.com/restful/rels/viewElements"
title="View Elements"
href="views/order" />
<atom:link
rel="http://www.denodo.com/restful/rels/viewAssociations"
title="View Associations"
href="views/order/$associations "/>
</view-metadata>
<view-metadata name="orderline">
…
<atom:link rel="self"
href="http://localhost:9090/denodo-restfulws/support"/>
</db>
By default, for security reasons, the Web container embedded in the
Denodo Platform (Apache Tomcat) returns an error (400 - Bad Request) if
the URL contains the characters %2F
or %5C
. They are
the URL-encoded characters for /
and \
respectively.
The appendix Allow URIs with Slash and Backslash in Apache Tomcat
explains how to disable this protection. You need to disable it if you
need to obtain the data of view contained in a database whose name
contains any of these characters.
XML Representation of a View¶
The figure below shows an example of the XML
representation of the view customer
of the database support
.
The URL to retrieve this document is something like this:
http://localhost:9090/denodo-restfulws/support/views/customer?$format=XML
This representation includes the name and description of the view and a
customer
element for each row of the view.
Each element has a link for each association of the view. This link traverses the association for that element (in the XML representation of a view, it returns the orders of a given customer).
By default, all the attributes of the view are returned. The section Parameters of the RESTful Web Service explains how to customize the output.
This representation supports pagination through the prev
and
next
links. They will only appear if the URL contains the parameters
$start_index
and/or $count
.
<?xml version="1.0" encoding="UTF-8"?>
<denodo:view name="customer"
xmlns="http://www.denodo.com/support/views/customer"
xmlns:denodo="http://www.denodo.com/restful"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<description>Acme customers</description>
<customer>
<cid>1</cid>
<cname>RoadRunner</cname>
<c_address>Monument Valley</c_address>
<c_description>He is fast</c_description>
<atom:link rel="self"
href="http://localhost:9090/denodo-restfulws/support/views/customer/1?$format=XML"/>
<atom:link
rel="http://localhost:9090/denodo-restfulws/support/views/customer/supportcases"
title="Support cases of this customer"
href="../supportcase?$filter=scid&3D1&$format=XML" />
<atom:link
rel="http://localhost:9090/denodo-restfulws/support/views/customer/orders"
title="Orders of this customer"
href="../order?$filter=oid&3D1&format=XML" />
</customer>
<customer>…</customer>
…
<atom:link rel="self"
href="http://localhost:9090/denodo-restfulws/support/views/customer?$format=XML"/>
<atom:link rel="prev" title="Previous"
href="?$count=10&$start_index=0">
<atom:link rel="next" title="Next"
href="?$count=10&$start_index=20">
</denodo:view>
Warning
The RESTful Web Service will return the HTTP code 406 (“Not acceptable”), if the name of the view or any of its fields contains characters that are not valid in the name of an XML element (e.g. “+”, “*”, space, etc.). This does not affect the HTML and the JSON representations.
When publishing a view as a REST Web service, Virtual DataPort will automatically remove the invalid characters from the names of the fields.
The Service does not return the values of the blob fields when you request a representation of the view. If the view has primary key, the result has a link to the blob value. For example:
<image xsi:nil="false">
<atom:link
rel="self"
type="multipart/mixed"
href="http://localhost:9090/denodo-restfulws/admin/views/customer/1?$format=xml&$select=image"/>
</image>
If the blob value is NULL
, the field is represented as an empty
element with the nil
attribute set to true
. For example,
<image xsi:nil="true"/>
If the view does not have primary key, the blob fields are represented
as empty elements with the attribute xsi:nil
set to true
or
false
depending on if the value is NULL
or not, respectively.
By default, for security reasons, the Web container embedded in the
Denodo Platform (Apache Tomcat) returns an error (400 - Bad Request) if
the URL contains the characters %2F
or %5C
. They are
the URL-encoded characters for /
and \
respectively.
The appendix Allow URIs with Slash and Backslash in Apache Tomcat
explains how to disable this protection. You need to disable it if you
need to obtain the data of view whose name contains any of these
characters.
XML Representation of a “View Element” Resource¶
The figure below shows an example of the XML representation of
a row of the view customer
, identified by its primary key.
The URL to retrieve this document is: http://localhost:9090/denodo-restfulws/support/views/customer/1?$format=XML
In this URL, 1
is the value of the primary key of the customer
view’s row.
If the view has one or more fields of type blob
, the response will
be a multipart message (i.e. with the HTTP header
Content-type: multipart/mixed
):
The first part of the message will be the XML document with the data.
The following parts contain the value of each blob field encoded in
base64
.
Each part of the message has its own Content-type
header. If you
have set the content type of a blob field (see section Working with Blob Fields of Base Views), the Service will set the value of the HTTP
header of its part, to the content type constant or the result of
evaluating its expression. Otherwise, the Content-type
will be
application/octet-stream
.
Note
The service only returns the links to traverse associations and retrieve blob values when the view has primary key.
<?xml version="1.0" encoding="UTF-8"?>
<customer xmlns="http://www.denodo.com/restful/support/views/customer"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<cid>1</cid>
<cname>RoadRunner</cname>
<c_address>Monument Valley</c_address>
<c_description>He is fast</c_description>
<atom:link rel="self"
href="http://localhost:9090/denodo-restfulws/support/views/customer/1"/>
<atom:link rel="http://localhost:9090/denodo-restfulws/support/views/customer/supportcases"
title="Support cases of this customer"
href="../supportcase?$filter=sid%3D1"/>
<atom:link rel="http://localhost:9090/denodo-restfulws/support/views/customer/orders"
title="Orders of this customer"
href="../order?$filter=oid%3D1"/>
</customer>
By default, for security reasons, the Web container embedded in the
Denodo Platform (Apache Tomcat) returns an error (400 - Bad Request) if
the URL contains the characters %2F
or %5C
. They are
the URL-encoded characters for /
and \
respectively.
The appendix Allow URIs with Slash and Backslash in Apache Tomcat
explains how to disable this protection. You need to disable it if you
need to obtain a view’s element whose primary key contains any of these
characters.
XML Representation of Array-Type Values¶
The Denodo REST web services simplify the values of array-type fields that only have one subfield. To do this, they omit the array and they only return the subfield of the array.
Note
This only applies to the XML representation of data, not to JSON nor HTML.
For instance, consider a web service that exposes a view with this schema:

Schema with nested arrays¶
In this case, if you access http://denodo-server.acme.com:9090/server/customer360/test_web_service/views/test_view?$format=xml, the service will return this:
<test_view>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
</test_view>
If you do not want the web service to simplify the output, follow these steps:
Log in as administrator and open the VQL Shell.
Execute this command:
SET 'com.denodo.wsgenerator.restws.xmlArraySimpleOutput' = 'false';
This change will affect all REST web services deployed after changing its value. You need to redeploy existing REST web services to update their configuration.
Redeploy the REST web services.
After performing these steps, the service will return this:
<test_view>
<f_n_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
</f_n_n>
<f_n_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
<f_n>
<f1>10</f1>
<f2>20</f2>
</f_n>
</f_n_n>
</test_view>
Note that after the change, the array f_n_n
is included in the result even though it only has one subfield (the register f_n
).
XML Representation of an Association¶
The metadata of an association provides information about an association and its two endpoints.
The figure below shows an example of the XML
representation of the association customer_order
.
The URL to retrieve this document is:
http://localhost:9090/denodo-restfulws/support/ associations/customer_order/$metadata?$format=XML
<association-metadata referential-constraint="false" name="customer_order">
<description>Association of customers and orders</description>
<endpoint
principal="false"
multiplicity="1"
role-description="Orders of this customer"
role-name="orders"
view-name="CUSTOMER"/>
<endpoint
principal="false"
multiplicity="0,*"
role-description="Customer of this order"
role-name="customer"
view-name="ORDER"/>
<ns2:link
href="associations/customer_order/$metadata"
rel="self"/>
</association-metadata>
JSON Representation¶
When a client selects the JSON representation, the Service returns a JSON document (JavaScript Object Notation) describing the requested element: a database, a view or a row of a view.
To select this representation, clients have to add the Accept
header
application/json
to the HTTP request or add the $format=JSON
parameter to the URL.
The JSON representation is equivalent to the XML representations.
{
"name": "customer",
"description": "Acme Customers",
"elements" : [
{
"cid": 1234,
"cname": "Roadrunner",
"address": "Monument Valley",
"description": "He is fast",
"links" : [
{
"rel": "self",
"href": "http://localhost:9090/denodo-restfulws/ support/views/customer/1234"
},
{
"rel":"http://localhost:9090/denodo-restfulws/support/views/customer/supportcases",
"title":"Support cases of this customer",
"href":"../supportcase?$filter=customer_id%3D1234"},
{
"rel": "http://localhost:9090/denodo-restfulws/support/views/customer/orders",
"title": "Orders of this customer",
"href": "../order=$filter=customer_id%3D1234"
}
]
},
{
"cid": 5678,
"cname": "Wile E. Coyote",
"address": "Flagstaff, Arizona",
"description": "He is fast",
"links" : [
{
"rel": "self",
"href": "http://localhost:9090/denodo-restfulws/ support/views/customer/5678"
},
{
"rel":"http://localhost:9090/denodo-restfulws/support/views/customer/supportcases",
"title":"Support cases of this customer",
"href":"../supportcase?$filter=customer_id%5678"},
{
"rel": "http://localhost:9090/denodo-restfulws/support/views/customer/orders",
"title": "Orders of this customer",
"href": "../order=$filter=customer_id%5678"
}
]
}
],
"links": [
{
"rel": "self",
"href": "http://localhost:9090/denodo-restfulws/support/views/customers"
},
{
"rel": "prev",
"title": "Previous",
"href": "?$count=2&$start_index=0"
},
{
"rel": "next",
"title": "Next",
"href": "?$count=2&$start_index=3"
}
]
The Service does not return the values of the blob fields when you request a representation of the view (i.e., when the URL does not have the primary key of a view’s row). If the view has primary key, the result contains a link to the blob value. For example:
"image": {
"rel": "self",
"type": "multipart/mixed",
"href": "http://localhost:9090/denodo-restfulws/admin/views/customer/1?$select=image"
}
If the blob value is NULL
, the field is represented as a null value.
For example, "image": null
.
If the view does not have primary key, the blob fields are represented
as an empty string (i.e. "image": ""
) or with null (i.e.
"image": null
) depending on if the value of the blob is NULL
or
not, respectively.
If the URL represents a “View element” (i.e. a row identified by its
primary key) and the view has a field of type blob
, the response is
a multipart message (i.e. with the HTTP header
Content-type: multipart/mixed
):
The first part of the message will be the JSON document with the data.
The following parts contain the value of each blob field encoded in
base64
.
Each part of the message has its own Content-type
header. If you
have set the content type of a blob field (see section Working with Blob Fields of Base Views),
the Service will set the value of the HTTP header of its part, to the
content type constant or the result of evaluating its expression.
Otherwise, the Content-type
will be application/octet-stream
.
Note
The service only returns the links to traverse associations and retrieve blob values when the view has primary key.
HTML Representation¶
The HTML representation is the default representation and is intended for human use.
The Service returns this representation if:
The user adds the
Accept
header to the HTTP request with the valuesapplication/xhtml+xml
ortext/html
.The user does not add the
Accept
header to the HTTP request.Or, the user does not add the
$format
parameter to the URL.

HTML representation of a view¶
There are a few differences between the HTML representation and the XML and JSON ones:
There is a query form for each view (see HTML query form) to filter the view elements, select the fields that will appear in the response and to order the results.
To access this form, click Search in the representation of the view.
The features provided by this form can also be obtained in the XML and JSON representations by adding certain parameters to the invocation URL (see section Parameters of the RESTful Web Service).
For each association of a view, there is a link to make easier browsing through the associations of views. The views associated with this view are listed in the “Related views” box.
Click get, next to “Total number of rows…” to obtain the total number of rows of the result set. That is, the total number of rows of the result set. This number may be higher than the number of rows you are seeing because the HTML representation displays the data paginated.
For example, if you are seeing the data of the view customer, by default the HTML representation will only show 25 rows, but if you click this link, the number will be all the rows of the view customer. That is because the service obtains this number by executing the query
SELECT_NAVIGATIONAL COUNT(*) FROM view WHERE …
When obtaining the number of rows, the service takes into account the conditions you set in the URL.
When a view has a field of type
blob
and the view has primary key, the Service represents its values with a link whose label is the name of the field. If you click on this link, the Service will return the value of the field with the appropriateContent-Type
HTTP header.If you have set the content type of the field (see section Working with Blob Fields of Base Views), the Service will set the value of the
Content-Type
HTTP header of its part, to the content type constant or the result of evaluating its expression. If you did not set the content type, the Service will try to guess it.If the view does not have primary key, the blob fields are hidden and you cannot request their values.
To begin using the service with different credentials, click the Logout link.
Although this service does not keep a session, the browsers usually send automatically, along with every request, the first valid credentials you entered. When you click “Logout”, the service indicates the browser that the user has to enter new credentials.
The other representations (JSON and XML) do not have this option because a client that wants to connect with different credentials, it just has to change the authentication headers of the requests it sends to the service.
Note
The service only returns the links to traverse associations and retrieve blob values when the view has primary key.

HTML query form¶
Parameters of the RESTful Web Service¶
You can customize the output of the RESTful Web service or Denodo REST Web services by adding certain parameters to the invocation URL.
For view resources, you can filter the elements by adding parameters to the URL with the following format:
fieldName1=value1&...&fieldNameN=valueN
.For example,
http://localhost:9090/denodo- restfulws/support/views/customer?cname=Acme
returns the elements of the customer view whose value of the
cname
attribute isAcme
.Note
In REST Web services, the fields that have been marked as “No searchable” cannot be used as parameters.
Note
When filtering by fields of type
date
, you must use theTO_DATE
function to create the date value. For example,http://.../view/date_field=TO_DATE%28%22yyyy-MM-dd%22,%222013-06-30%22%29
The last part of the URL is equivalent to
TO_DATE('yyyy-MM-dd','2013-06-30')
, but URL encoded. See more about the functionTO_DATE
in the appendix TO_DATE of the VQL Guide.For view resources, you can obtain a row by specifying its primary key.
For example,
http://.../support/views/customer/1
returns the row of the viewcustomer
whose primary key has value1
. If the primary key is formed by more than one field, you have to separate its values with comma. For examplehttp://.../support/views/viewA/1,value1
.When the value is a date, you have to enter the date in the following format:
<year><month><day>T<hour>:<minute>:<second><time zone>
For example,
http://.../view/2012-06-14T22:00:00+0000
For view resources, to traverse an association you have to specify the primary key of a row and the name of the endpoint of the association. E.g.
http://.../support/views/customer/1/orders
Parameters of the Web Service RESTful and REST Web Services |
|
---|---|
$filter |
Filters the rows of a view using any condition. Any expression that can appear in the WHERE clause of a VQL query can be used. I.e. this parameter can contain VQL functions, any operator, etc. As in a VQL query, in the The last part of the URL is equivalent to
The double quotes are only necessary in the $filter parameter
and not in the parameters like To filter by a date field, you must use the E.g., http://…/view?$filter=date_field%3C%3ETO_DATE%28%22yyyy-MM-dd%22,%222013-06-30%22%29 The last part of the URL is equivalent to
See more about the function TO_DATE in the appendix TO_DATE of the Advanced VQL Guide Note The fields that have been marked as “No searchable” cannot be added to this parameter. |
$select |
The values allowed in this parameter depend on the check box Process functions in $select parameter (tab Advanced of the configuration of the service):
By default, the global RESTful web service only supports field names in the parameter $select, not functions. The section Configuring the RESTful Web Service explains how to enable this feature. Note If the view has primary key and associations, the
output also includes the information about the associations
of each row. If you do not want this information, add the parameter
|
$groupby |
Comma-separated list of fields to group by with. E.g., http://…/view?$groupby=Name&$select=Name Adding a field to this parameter is equivalent to adding it to the GROUP BY clause of a SQL statement. Therefore, if you add this parameter, you also have to add $select and only select fields listed in the parameter $groupby. The main use for the GROUP BY is to be able to perform a DISTINCT. I.e. to only obtain the rows that are different (like adding the clause DISTINCT to a SQL statement). To do this, add all the fields of the view to this parameter. |
$having |
Comma-separated list of fields to add to the HAVING clause of the query. E.g., http://…/customer?$select=state&$groupby=state&$having=%27CA%27 %27 is the single quote encoded. |
$start_index and $count |
Used for pagination in view resources. For example,
http://…/customer?$start_index=0&$count=10
returns the first 10 elements of the result (the first element has
|
$orderby |
Sorts the results by one or more fields. It is a comma-separated list of fields, each one followed by the modifier ASC (for ascending order) and DESC (for descending order). For example, http://…/support/views/customer?$orderby=cid+ASC Note In REST Web services, the fields that have been marked as “Do not output” cannot be added to this parameter. |
$format |
Selects the representation of the data. This parameter is an alternative to sending the HTTP header Accept. The value of this parameter overrides the value of the Accept header. Possible values:
In REST Web services, the possible values are the “Available representations” selected in the “Create REST Web service” dialog (see section Selecting the Default / Available Representations) |
$jsoncallback |
The JSON representation can return the data of a view prefixed with the name of a function. This is called JSON with padding or JSONP. That way, when a browser receives the response, it receives a script rather than data. To obtain JSON with padding, add the parameter For example: http://localhost:9090/denodo-restfulws/support/views/incidents?$format=JSON&$jsoncallback=js_function returns the following js_function(
<result of the query>
)
If you request the number of rows of a result set and add this parameter, it returns the number of rows as a parameter of a function For example http://localhost:9090/denodo-restfulws/support/views/incidents/$count?state=California&$format=JSON&$jsoncallback=js_function return this:
This parameter is ignored when requesting a representation other than JSON. |
$displayRESTfulReferences |
By default, the result of requesting a view contains, in each row, a link to the row itself and, for each association of the view, a link to traverse the association. If you do not want the result to include these links, add the p arameter displayRESTfulReferences=false. In REST Web services published with the option “Display RESTful links” cleared, this parameter is ignored (see section Settings Tab (REST)). |
$noescapeHTML |
List of comma-separated fields whose values will not be HTML escaped. By default, in the HTML representation, all the values of type For example, if the value of a value of a field is
To avoid this, add the parameter See more about this in the section HTML-Escaping the Data. |
The following examples illustrate the use of some of these options:
Query |
Result |
---|---|
/customer?cname=RoadRunner |
Customer with cname = ‘RoadRunner’ |
/customer?$select=cid,cname&$filter= (cname = ‘RoadRunner’ or cname = ‘Coyote’)&$orderby=cid DESC’ |
Fields cid and cname of customers whose cname is either RoadRunner or Coyote, ordered by cid in descending order. |
/customer?$format=json&$start_index =10&$count=10 |
Elements 11 to 20 of the customer view, in JSON format. |
Note
When you have to provide a list of fields/values separated
by commas and one of the fields/values has a comma, replace it with
%2C
. For example,
http://.../viewA/1,value%2Cwith%2Ccommas
http://.../viewA/$select=fieldname%2Cwith%2Ccommas&$orderby=fieldname%2Cwith%2Ccommas
Tunnel HTTP Methods inside another HTTP Method (X-HTTP-Method-Override)¶
The RESTful web service and published REST web services support the HTTP header X-HTTP-Method-Override
. This header allows applications to “tunnel” other HTTP methods inside POST requests. For example, a POST request with the header X-HTTP-Method-Override: GET
will be processed as a GET request. In addition, you can send the query parameters in the body of the request instead of in the query of the URL.
This is useful when:
There is a firewall between the client application and the Denodo server, and the firewall only allows the methods GET and POST, but not PUT nor DELETE.
The application needs to send extremely long input parameters that result in the URL being longer than the maximum length of an HTTP request. In this case, the application can send a POST request with this header and put the input parameters in the body of the request, instead of in the URL.
You can tunnel the following methods inside a POST request: GET, PUT and DELETE.
If a request contains the header X-HTTP-Method-Override and the request is not POST, the header is ignored and the request is processed as it is.
When you tunnel a PUT request inside a POST request, the request is processed as a PUT. In this case, the client has to send the same body as if it was sending a PUT request.
When you tunnel a GET or DELETE request inside a POST request, you can put the parameters in the body of the request instead of in the URL. The parameters you can put in the body are the same you can put in the URL: field names, $filter, $select, $orderby, etc. They can be put in an XML document, a JSON or an HTML form, and the request has to have the header Content-Type
. This header is only used to process the body of the request; the output is still determined by the Accept
header or the parameter $format
of the URL.
Sending Input Parameters in an XML Document
To send the input parameters in the body of the request, as an XML document, add the HTTP header Content-Type: application/xml
. We recommend setting the encoding of the input so the non-ASCII characters are processed correctly. E.g. application/xml;charset=UTF-8
.
The format of the XML has to be:
<request>
<parameter name="name of parameter 1">value of parameter 1</parameter>
<parameter name="name of parameter 2"> value of parameter 2</parameter>
<!-- ... -->
<!-- ... -->
</request>
For example:
POST /server/customer360/customer HTTP/1.1
X-HTTP-Method-Override: GET
Content-Type: application/xml;charset=UTF-8
Accept: application/xml
<request>
<parameter name="country">Mexico<parameter>
<parameter name="$select">client_id,name,company_name</parameter>
<parameter name="$orderby">client_id</parameter>
</request>
This is equivalent to sending a GET request to
/server/customer360/customer?country=Mexico&$select=client_id,name,company_name&order_by=client_id
The service will return the information about customers in Mexico, sorted by client_id.
Sending Input Parameters in a JSON Document
To send the input parameters in the body of the request, in a JSON document, add the HTTP header Content-Type: application/json
. We recommend setting the encoding of the input so the non-ASCII characters are processed correctly. E.g. application/json;charset=UTF-8
.
The format of the JSON has to be:
{
"name of parameter 1": "value of parameter 1"
, "name of parameter 2": "value of parameter 2"
}
For example:
POST /server/customer360/customer HTTP/1.1
X-HTTP-Method-Override: GET
Content-Type: application/json;charset=UTF-8
Accept: application/json
{
"country": "Mexico"
, "$select": "client_id,name,company_name"
, "$orderby": "client_id"
}
This is equivalent to sending a request to
/server/customer360/customer?country=Mexico&$select=client_id,name,company_name&order_by=client_id
Sending Input Parameters in an HTML Form
To send the input parameters in the body of the request, in an HTML form, add the HTTP header Content-Type: application/x-www-form-urlencoded
. We recommend setting the encoding of the input so the non-ASCII characters are processed correctly. E.g. application/x-www-form-urlencoded;charset=UTF-8
.
The values are encoded in key-value tuples separated by “&”, with a “=” between the key and the value. Non-alphanumeric characters are percent encoded. E.g. if a value has the character “%”, put “%25”.
For example:
POST /server/customer360/customer HTTP/1.1
X-HTTP-Method-Override: GET
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept: text/html
state=New%20Jersey&$select=client_id,name,company_name&$orderby=client_id
This is equivalent to sending a request to
/server/customer360/customer?country=New%20Jersey&$select=client_id,name,company_name&order_by=client_id
Because of the header Accept, the service will return the HTML representation of the data.