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 Input 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>
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 Input 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.
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>
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 main goal of the HTML representation is to validate the output of the XML and JSON representation. For more advanced features, use the Data Catalog whose main goal is to help business users to query, search and browse data accessible through Denodo.
The Service returns the HTML 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.
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 Input 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.
If you access a published REST web service with OAuth or SAML authentication, the service does not display any of these links. The RESTful web service and the REST web services are stateless (one of the principles of REST) so there is no session. This implies that the client applications (for example, you browser) have to send the credentials in each request. Browsers do this when the authentication method is HTTP Basic and HTTP Digest (username and password). However, when the authentication is OAuth or SAML, browsers do not send the credential. If the web services displayed these links when the authentication is OAuth or SAML, they would not work so we chose to hide them instead.