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

<?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>

<image xsi:nil="false">
  <atom:link
    rel="self"
    type="multipart/mixed"
    href="http://localhost:9090/denodo-restfulws/admin/views/customer/1?$format=xml&amp;$select=image"/>
</image>

<?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>

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:

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

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

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¶

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.

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

js_function(
   <result of the query>
)

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

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.