BusinessObjects Explorer (formerly known as Polestar) OnDemand API

Please keep in mind that the BusinessObjects Explorer (formerly known as Polestar) OnDemand product is for preview and is not a representation of product that is currently shipping or that may ship in the future. This API valid for http://create.ondemand.com otherwise known as 'Whohar'. The REST API for Whohar allows you to work with datasets and view them with Polestar. If you have any comments or questions you can post them to this page. As we find bugs, make updates, and add sample code we will add them to this wiki page. Also stay tuned for more information on an innovation challenge which will award $20,000 to the developer who has create the most interesting mashup with this API.

The version of Polestar OnDemand that is being used with this API can be found at http://create.ondemand.com/polestar

General Notes

All requests must use https (if you use http, they are redirected to https).
Authentication is supplied using HTTP Basic Authentication. Some of the actions do not require authentication e.g. GETing a public dataset. Other actions give different results depending on whether you are authenticated or not e.g. the summary listing will contain your private datasets if authentication is supplied. In general, you can only perform those actions that you could within the application itself. For example, you are only able to delete your own datasets. Note that anonymous POST is supported.
curl (http://curl.haxx.se/ ) is a nice way to test this functionality out. The GET requests can be tested just within your browser.

Getting a dataset:

GET https://create.ondemand.com/v1/datasets/id
GET https://create.ondemand.com/v1/datasets/HjRFGTVCjAiybr-fEqK502

To get an XML representation of the dataset, including description, tags, source, and the data, including formulas, types, null and error values.
Note that there is also a SOAP-based web service for datasets. The WSDL of a dataset is accessed via:

https://create.ondemand.com/datasets/wsdl/id

https://create.ondemand.com/datasets/wsdl/HjRFGTVCjAiybr-fEqK502

This differs from the above in that it doesn't include the metadata about the dataset, but is more of a standardized representation of the dataset useful for interacting with pre-existing clients.

Deleting a dataset:

DELETE https://create.ondemand.com/v1/datasets/id

returns HTTP 200 OK if successful
If your client does not support DELETE, you can use the _method=DELETE query parameter in a
POST instead to have the same effect e.g.

Creating a new dataset:

POST https://create.ondemand.com/v1/datasets

returns HTTP 201 Created if successful, with the URL of the created dataset is in the Location header of the HTTP response
the format of the body XML should be similar to what you get from a GET. The difference is that some of the elements and attributes are ignored since they are read only i.e. you can't set the rating or view count for example.
set the Content-Type HTTP header to text/xml
if authentication is not supplied, the POST will succeed using a session user. The client can then get the value of the _whohar_session cookie, and open up the dataset for viewing
e.g. This displays the dataset inside of a Whohar workflow https://create.ondemand.com/datasets/show/?_whohar_session=<_whohar_session>
e.g. This displays the dataset inside of Polestar OnDemand https://create.ondemand.com/polestar/show_exploration/?_whohar_session=<_whohar_session>
Note: if you do supply authorization, and it is incorrect, then you will get an unauthorized response.
Maximum Dataset size is 20,000 rows and 256 colums, *** Subject to change

Viewing Datasets

GET https://create.ondemand.com/datasets/show/?_whohar_session=whohar_session

Above link displays the dataset inside Polestar

GET https://create.ondemand.com/polestar/show_exploration/?_whohar_session=whohar_session

Above link displays the dataset inside of Whohar
Note: if you do supply authorization, and it is incorrect, then you will get an unauthorized response.

Updating an existing dataset

PUT https://create.ondemand.com/v1/datasets/id

this overwrites an existing dataset with a new representation
can only replace true text datasets (not query, polestar, mashup, dapp, etc)
set the Content-Type HTTP header to text/xml
If your client does not support PUT, you can use the _method=PUT query parameter in a
POST instead to have the same effect e.g.

Get a summary listing of all datasets in Whohar:

GET https://create.ondemand.com/v1/datasets

will show at most 10 datasets, not all. You can see more by using the page parameter.
has 5 optional paramaters for controlling what datasets are shown.
- user_id -shows only the datasets owned by that user. Can use the special value "me" to use the authenticated user.
- shared_with_user_id -shows only the datasets shared with that user. Can use the special value "me" to use the authenticated user
- sort_order- must be one of: 'most_views', 'date', 'highest_rating', 'most_voted', or 'alphabetical_order'
- time_filter- must be one of: 'anytime', 'today', 'last_7_days', or 'this_month'
- page- to indicate the page shown
The defaults are page=1, time_filter=anytime, sort_order=most_views and no user_id or shared_with_user_id specified, so get datasets owned by any user (that the authenticated user has rights to see).
Note that if the request is authenticated then the listings may change. For example, if you are authenticated and ask to see your datasets, then you will see the public and private datasets, but a non-authenticated request will only return public datasets.

Example of the body XML

Below is an example that shows almost all of the features of a Whohar dataset. Some things to note:

The valid types in Whohar are string, number, currency, date, dateTime, time and boolean. These are exactly like the corresponding types in Crystal Reports.
The element names for parts of the rowset are r, v and e which are short for row, value and error. They are only 1 character long for file size reasons since the tables can get large.
Null values are encoded as <v/>.
Non-null values are serialized according to the XML schema types: xsd:string, xsd:number (for both number and currency), xsd:boolean, xsd:date, xsd:time, xsd:dateTime. See http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes  with the following restrictions on date, time and dateTime due to the fact that the Whohar date-like types are relative types and do not support time zones, fractional seconds, etc. For the date-like types, a useful explanation is on the Wikipedia page for ISO-8601.
- date must be of the form YYYY-MM-DD (zero-padding required e.g. 2008-09-27).
- time must be of the form hh:mm:ss (zero-padding required e.g. 05:00:00, 15:30:00).
- dateTime must be of the form YYYY-MM-DDThh:mm:ss (zero-padding required, the 'T' between the date part and the time part is required e.g. 2008-09-27T05:00:00)
The type of a column is determined by the type of its corresponding field.
Any cell can be an error instead of a value. For example, <e>not really a boolean</e>, in the xml below. This is a way to include data that doesn't fit the type scheme e.g. needs manual correction.

the qualification node has a type attribute that is either dimension or measure. If the type is measure, the aggregation attribute must be present and can be sum, average, max, min, or count. Not all combinations are legal for all field types.

<?xml version="1.0" encoding="UTF-8"?>
<dataset name="All types in Whohar with error values and formulas"
 id="CunZvRE2ideTWL5AvzCF0K"
 visibility="public"
 created_on="2008-12-01T17:05:00"
 view_count="0" rating_avg="0.0">
 <owner name="Bo Ilic" id="Wh53blV9jgyZjhFZU93u2X"/>
 <source>test data</source>
 <description>This dataset has a column of each of the supported types in Whohar.
It has 3 rows of data, with some of the values in the 3rd row being "error" values.
There are 2 formula fields, including a multi-line formula.
</description>
 <tags>
  <tag name="mostly harmless"/>
  <tag name="Deep Thought"/>
  <tag name="The Hitch Hiker's Guide to the Galaxy"/>
 </tags>
 <table>
  <fields>
   <field name="Text Field" type="string">
    <qualification type="dimension"/>
   </field>
   <field name="Boolean Field" type="boolean">
    <qualification type="dimension"/>
   </field>
   <field name="Formula on Number Field" type="number">
    <qualification type="measure" aggregation="sum"/>
    <formula syntax="crystal">if {Number Field} &gt; 123 then
    {Number Field} * 5
else
    -{Number Field}
</formula>
   </field>
   <field name="Number Field" type="number">
    <qualification type="measure" aggregation="average"/>
   </field>
   <field name="Currency Field" type="currency">
    <qualification type="measure" aggregation="count"/>
   </field>
   <field name="Date Field" type="date">
    <qualification type="measure" aggregation="max"/>
   </field>
   <field name="Time Field" type="time">
    <qualification type="measure" aggregation="min"/>
   </field>
   <field name="DateTime Field" type="dateTime"/>
   <field name="Formula reverses Text Field" type="string">
    <formula syntax="crystal">StrReverse({Text Field})</formula>
   </field>
  </fields>
  <rows>
   <r>
    <v>Zaphod Beeblebrox</v>
    <v>false</v>
    <v>617.25</v>
    <v>123.45</v>
    <v>456.78</v>
    <v>2007-04-25</v>
    <v>23:15:30</v>
    <v>2007-04-25T23:15:30</v>
    <v>xorbelbeeB dohpaZ</v>
   </r>
   <r>
    <v>Ford Prefect</v>
    <v>true</v>
    <v>-123</v>
    <v>123</v>
    <v>928.67</v>
    <v>2008-10-16</v>
    <v>10:30:00</v>
    <v>2008-10-16T10:30:00</v>
    <v>tceferP droF</v>
   </r>
   <r>
    <v>Mostly nulls</v>
    <v/>
    <v/>
    <v/>
    <v/>
    <v/>
    <v/>
    <v/>
    <v>sllun yltsoM</v>
   </r>
   <r>
    <v/>
    <v>true</v>
    <v/>
    <v/>
    <v/>
    <v/>
    <v/>
    <v/>
    <v/>
   </r>
   <r>
    <v>Planet Earth</v>
    <e>not really a boolean</e>
    <e>not really a number</e>
    <e>not really a number</e>
    <v>-100.1234</v>
    <v>2009-01-01</v>
    <v>09:09:09</v>
    <e>not really a date</e>
    <v>htraE tenalP</v>
   </r>
  </rows>
 </table>
</dataset>

Format of body XML for a POST or PUT

It is possible to GET and then POST the representation that you got to create a new dataset. However, certain attributes are ignored in the POST, as they are calculated by the system and not user settable, and they are not required e.g. /dataset/@id, /dataset/@created_on, /dataset/@view_count, etc. You can omit nodes that are not needed e.g. you don't need a /dataset/tags node if there are no tags and you don't need a /dataset/table/rows if you want a dataset with no rows (only schema information).
/dataset/@name and /dataset/source are required.
Note that the values of formula columns are ignored- the client does not need to calculate formulas, this is done by Whohar. You should just put a null as a placeholder for that column value i.e. <v/>
the qualification node is optional.

Workaround for Clients not supporting non-200 OK response codes

If the url parameter/value pair suppress_response_codes=true is present, then the REST api request returns HTTP response code 200 OK for most requests, including errors, except for some unrecoverable 500 level errors and authentication errors. In particular, it will work this way for POST requests when a new dataset is created (and the usual response is 201 Created) and for POST requests where there are various syntax errors in the body XML. The client must parse the response body to determine if the true response was an error.This feature is based on the workaround added Dec 2008 to the Twitter REST API and the same caveats apply:http://apiwiki.twitter.com/REST-API-Documentation?SearchFor=suppress_response_codes&sp=2"suppress_response_codes: If this parameter is present, all responses will be returned with a 200 OK status code - even errors. This parameter exists to accommodate Flash and JavaScript applications running in browsers that intercept all non-200 responses. If used, it's then the job of the client to determine error states by parsing the response body. Use with caution, as those error messages may change."

Questions and Answers

Q1. When I push up data where the dataset XML formatting is incorrect, I only get back a HTTP 401 "Bad Request" - are there any way to get more info concerning what went wrong?

A1. The error messages should be in the body of the response (not as part of the HTTP status code).

Sample Code

https://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/13458

Page tree