USER MANUALS

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.

Representation returned by a RESTful Web service depending on the Accept HTTP header

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 and next 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 representation of a database
<?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.

Sample XML representation of a view
<?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:

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 representation of an element
<?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

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:

Simplified XML representation of an element with nested array values
<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:

  1. Log in as administrator and open the VQL Shell.

  2. 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.

  3. Redeploy the REST web services.

After performing these steps, the service will return this:

XML representation of an element with nested array values
<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

Sample XML representation of an association
<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.

Sample JSON representation of a view
{
  "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:

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 values application/xhtml+xml or text/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

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 appropriate Content-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

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 is Acme.

    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 the TO_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 function TO_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 view customer whose primary key has value 1. If the primary key is formed by more than one field, you have to separate its values with comma. For example http://.../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 supported by the Denodo RESTful Web service and published REST Web services

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 $filter parameter, the names of the fields with non-standard or uppercase characters have to be surrounded with double quotes. E.g. http://…/view?$filter=TRIM(%22fieldWithUpperCase%22)%3C%3E%27value%27

The last part of the URL is equivalent to TRIM("fieldWithUpperCase")<>'value', but URL encoded.

The double quotes are only necessary in the $filter parameter and not in the parameters like <field name>=<value>

To filter by a date field, you must use the TO_DATE function to create the date value.

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 date_field<>TO_DATE('yyyy-MM-dd','2013-06-30'), but URL encoded.

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):

  • If selected (default): it is a comma-separated list of expressions. These are the same expressions you can use in the SELECT clause of a query.

    Example: http://…/views/customer?$select=concat(last_name, ‘, ‘ , first_name) AS full_name, upper(state)

    (for clarity purposes, this URL is not escaped)

    Note that you can add an alias with “AS” to the result of a expression.

  • If cleared: it is a comma-separated list of fields of the view.

    Example: http://…/support/views/customer?$select=cid,cname

    This returns the fields “cid” and “cname” fields of the view “customer”.

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 $displayRESTfulReferences=false to the URL or in the configuration of the service, clear the check box Display RESTful links (Settings tab).

$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 start_index=0).

$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:

  • JSON

  • XML

  • Or, HTML

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 $jsoncallback to the URL, along with the name of the function.

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:

js_function(9382) being 9382 the number of rows of the view incidents that meet the condition state = ‘California’.

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 text are HTML escaped.

For example, if the value of a value of a field is <a href="http://www.denodo.com">link</a>, the user will see this text and not a link to http://www.denodo.com

To avoid this, add the parameter $noescapeHTML=fieldname to not escape the values of the field fieldname.

See more about this in the section HTML-Escaping the Data.

The following examples illustrate the use of some of these options:

RESTful Web service: samples of URLs with parameters

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:

  1. 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.

  2. 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.

Add feedback