Access data using REST APIs

 

Is there data from another app that you want to display with Project Siena? If that data can be accessed with REST API calls, you can retrieve and display it in a Project Siena app. For example, you can display data from Coursera, DropBox, Visual Studio Online, or your own REST API service in your Project Siena app. If you are a business user and are not sure how to use REST API calls, find a developer who can help you create a WADL file. Then you can load this file and create your Project Siena app with the data.

Project Siena apps access the data from a service using a WADL file. This WADL file is simply an XML file that tells Project Siena how to access the REST based web service and the data that is returned. The WADL files are created with a specific format based on the WADL standard. You can use basic or OAuth authentication to access the data from your Project Siena app with a WADL file. Pass parameters to the REST API calls from your Project Siena app to customize the data that is returned. These parameters can be entered specifically when you design your app, or they can be the value of another field in your Project Siena app.

If you already have a WADL file, jump ahead to learn how to load your WADL file and access your data.

Create a WADL file

There are three ways to create a WADL file for Project Siena.

  • Generate a WADL file using a WADL generator tool to help you

  • Use an existing sample and modify it if necessary

  • Manually create a WADL file

Generate a WADL file

The WADL generator tool is not supported, but in most situations can generate a file for you much more quickly than creating it manually. You can use this file as a basis for any necessary modifications that you may need. Download the tool now.

If the REST API service that you want to access uses OAuth to authenticate users, you will often need to create an app for that service first. This will give you the client ID that you need. You will also need to provide a callback URL to the tool. This is just a placeholder URL as you are not authenticating from a web app, so simply provide a valid URL. This URL is not used, but the WADL generator tool must be able to load the page.

  1. Start the WADL generator. Create a new WADL. Name it based on your service.

  2. Add any functions that you want to use from your service. When you load the WADL file into Project Siena, these functions will be displayed with the same names.

    For some REST services that use OAuth 2.0 authentication, you will get an error when you try out the function that you have added. In this case, paste a sample response into the tool that would be returned by this call to the REST API. Then save the function.

  3. Export the generated WADL file and save as an xml file to use from Project Siena.

    Don't forget to save a WADL generation file when you exit the tool. That way you can use the tool to add more functions in the future to your WADL file.

Take a look in the sample WADL files section below to see what a WADL file should look like.

Now load your WADL file and access your data in your Project Siena app to test it works correctly.

Sample WADL files

You can copy the xml from the samples below to create your own .xml file.

  • Coursera

  • Dropbox (uses OAuth 2.0 authentication)

Coursera sample WADL file

This is a very basic WADL file that simply accesses the courses from Coursera without any authentication.

  <?xml version="1.0" encoding="utf-16"?>
    <application xmlns:siena="https://schemas.microsoft.com/MicrosoftProjectSiena/WADL/2014/11" 
                        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                        xmlns:sienatool="http://www.todo.com" 
                        siena:serviceId="CourseraREST" 
                        xmlns="http://wadl.dev.java.net/2009/02">
      <grammars>
        <siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
          <siena:object name="GetCourses_Root">
            <siena:property name="elements" typeRef="GetCourses_elements_Array" />
            <siena:property name="linked" typeRef="GetCourses_linked_Object" />
          </siena:object>
          <siena:object name="GetCourses_elements_Object">
            <siena:property name="id" type="number" />
            <siena:property name="shortName" type="string" />
            <siena:property name="name" type="string" />
            <siena:property name="links" typeRef="GetCourses_links_Object" />
          </siena:object>
          <siena:object name="GetCourses_links_Object" />
          <siena:array name="GetCourses_elements_Array" typeRef="GetCourses_elements_Object" />
          <siena:object name="GetCourses_linked_Object" />
        </siena:jsonTypes>
      </grammars>
      <siena:authenticationProviders />
      <siena:template />
      <resources base="https://api.coursera.org">
        <resource path="api/catalog.v1/courses">
          <method name="Get" id="GetCourses" siena:requiresAuthentication="false">
            <request />
            <response siena:resultForm="single">
              <representation mediaType="application/json">
                <param name="GetCourses_Name" type="sienatool:GetCourses_Root" style="Plain" path="" />
              </representation>
            </response>
          </method>
        </resource>
      </resources>
    </application>

Dropbox sample WADL file

This sample file uses OAuth 2.0 authentication and contains two functions:

  • GetFileAndFolderInfo gets the file and folder information from Dropbox for a specific folder

  • DisplayImage gets the URL to display an image stored on Dropbox.

When you add items in Project Siena that use these functions, you can specify the folder and the location for the image. These strings can be the text from another field in your Project Siena app. That field could be data from a call to a REST API too.

<?xml version="1.0" encoding="utf-16"?>
<application xmlns:siena="https://schemas.microsoft.com/MicrosoftProjectSiena/WADL/2014/11" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sienatool="http://www.todo.com" siena:serviceId="Dropbox" xmlns="http://wadl.dev.java.net/2009/02">
  <grammars>
    <siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
      <siena:object name="GetFileAndFolderInfo_Root">
        <siena:property name="read_only" type="boolean" />
        <siena:property name="hash" type="string" />
        <siena:property name="revision" type="number" />
        <siena:property name="bytes" type="number" />
        <siena:property name="thumb_exists" type="boolean" />
        <siena:property name="rev" type="string" />
        <siena:property name="modified" type="string" />
        <siena:property name="size" type="string" />
        <siena:property name="path" type="string" />
        <siena:property name="is_dir" type="boolean" />
        <siena:property name="modifier" type="string" />
        <siena:property name="root" type="string" />
        <siena:property name="contents" typeRef="GetFileAndFolderInfo_contents_Array" />
        <siena:property name="icon" type="string" />
      </siena:object>
      <siena:object name="GetFileAndFolderInfo_contents_Object">
        <siena:property name="rev" type="string" />
        <siena:property name="thumb_exists" type="boolean" />
        <siena:property name="path" type="string" />
        <siena:property name="is_dir" type="boolean" />
        <siena:property name="client_mtime" type="string" />
        <siena:property name="icon" type="string" />
        <siena:property name="read_only" type="boolean" />
        <siena:property name="modifier" type="string" />
        <siena:property name="bytes" type="number" />
        <siena:property name="modified" type="string" />
        <siena:property name="size" type="string" />
        <siena:property name="root" type="string" />
        <siena:property name="mime_type" type="string" />
        <siena:property name="revision" type="number" />
      </siena:object>
      <siena:array name="GetFileAndFolderInfo_contents_Array" typeRef="GetFileAndFolderInfo_contents_Object" />
    </siena:jsonTypes>
    <siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
      <siena:object name="DisplayImage_Root">
        <siena:property name="url" type="string" dtype="hyperlink" />
        <siena:property name="expires" type="string" />
      </siena:object>
    </siena:jsonTypes>
  </grammars>
  <resources base="https://api.dropbox.com" siena:authenticationProviderHref="#Dropbox_Auth">
    <resource path="1/metadata/auto/photos">
      <method name="Get" id="GetFileAndFolderInfo" siena:requiresAuthentication="true">
        <request>
          <param name="list" style="Query" required="true" siena:sampleDefault="true" />
        </request>
        <response siena:resultForm="single">
          <representation mediaType="application/json">
            <param name="GetFileAndFolderInfo_Name" type="sienatool:GetFileAndFolderInfo_Root" style="plain" path="" />
          </representation>
        </response>
      </method>
    </resource>
  </resources>
  <resources base="https://api.dropbox.com" siena:authenticationProviderHref="#Dropbox_Auth">
    <resource path="1/media/auto/">
      <method name="Get" id="DisplayImage" siena:requiresAuthentication="true">
        <request>
          <param name="path" style="Query" required="true" siena:sampleDefault="/Photos/i-b858zMh-M.jpg" />
        </request>
        <response siena:resultForm="single">
          <representation mediaType="application/json">
            <param name="DisplayImage_Name" type="sienatool:DisplayImage_Root" style="plain" path="" />
          </representation>
        </response>
      </method>
    </resource>
  </resources>
  <siena:authenticationProviders>
    <siena:oauth2 id="Dropbox_Auth">
      <siena:grantType>
        <siena:implicit>
          <siena:endpoints>
            <siena:authorization url="https://www.dropbox.com/1/oauth2/authorize" />
            <siena:callback url="https://fabrikam-prime-oauth.azurewebsites.net/" />
          </siena:endpoints>
          <siena:credentials clientId="[templated]" />
        </siena:implicit>
      </siena:grantType>
      <siena:resourceAuthorization placement="Query" />
    </siena:oauth2>
  </siena:authenticationProviders>
  <siena:template>
    <siena:variable name="Dropbox__ClientID">
      <siena:doc title="Client ID/API Key" />
      <siena:modifyAuth tag="credentials" href="#Dropbox_Auth" attribute="clientId" />
    </siena:variable>
    <siena:variable name="Dropbox__URI">
      <siena:doc title="Redirect URI" />
      <siena:modifyAuth tag="callback" href="#Dropbox_Auth" attribute="url" />
    </siena:variable>
  </siena:template>
</application>

Add sections manually

Each WADL file needs the following elements:

  • <application> - the root element

  • <grammars> - defines formats of the returned data.

  • <resources> - contains the REST API call and any parameters for each method that you call.

  • <siena:authenticationProviders> - empty unless you need authentication to access the REST API.

  • <siena:template> - provides the details for the authentication if it is required, otherwise it's empty.

Some of the elements are extensions to the WADL standard specific to Project Siena. There are also some differences to the standard too. The extensions and differences are described in this section.

<application>

This is the root element that you will need to add to your XML file. Replace <name_of_your_service> with whatever your service is called. This is the name that you will see in Project Siena when you load your WADL file.

  <application xmlns:siena="https://schemas.microsoft.com/MicrosoftProjectSiena/WADL/2014/11" 
                                     xmlns:xs="http://www.w3.org/2001/XMLSchema"  
                                     siena:serviceId="<name_of_your_service>" 
                                     xmlns="http://wadl.dev.java.net/2009/02">
             <!-- Add the other elements here -->
</application

<grammars>

This defines the format of the data whether it is JSON or XML and what the fields are called and the type. In this example, the data is JSON. If your REST API call returns XML, then you add an element <siena:sampleXmlTypes> instead.

   <grammars>
    <siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
      <siena:object name="GetFileAndFolderInfo_Root">
        <siena:property name="read_only" type="boolean" />
        <siena:property name="hash" type="string" />
        <siena:property name="revision" type="number" />
        <siena:property name="bytes" type="number" />
        <siena:property name="thumb_exists" type="boolean" />
        <siena:property name="rev" type="string" />
        <siena:property name="modified" type="string" />
        <siena:property name="size" type="string" />
        <siena:property name="path" type="string" />
        <siena:property name="is_dir" type="boolean" />
        <siena:property name="modifier" type="string" />
        <siena:property name="root" type="string" />
        <siena:property name="contents" typeRef="GetFileAndFolderInfo_contents_Array" />
        <siena:property name="icon" type="string" />
      </siena:object>
      <siena:object name="GetFileAndFolderInfo_contents_Object">
        <siena:property name="rev" type="string" />
        <siena:property name="thumb_exists" type="boolean" />
        <siena:property name="path" type="string" />
        <siena:property name="is_dir" type="boolean" />
        <siena:property name="client_mtime" type="string" />
        <siena:property name="icon" type="string" />
        <siena:property name="read_only" type="boolean" />
        <siena:property name="modifier" type="string" />
        <siena:property name="bytes" type="number" />
        <siena:property name="modified" type="string" />
        <siena:property name="size" type="string" />
        <siena:property name="root" type="string" />
        <siena:property name="mime_type" type="string" />
        <siena:property name="revision" type="number" />
      </siena:object>
      <siena:array name="GetFileAndFolderInfo_contents_Array" typeRef="GetFileAndFolderInfo_contents_Object" />
    </siena:jsonTypes>
    <siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
      <siena:object name="DisplayImage_Root">
        <siena:property name="url" type="string" dtype="hyperlink" />
        <siena:property name="expires" type="string" />
      </siena:object>
    </siena:jsonTypes>
  </grammars>

<resources>

When accessing a REST resource, a typical starting point is a resource URI also known as a REST endpoint. For example, https://api.dropbox.com.

In WADL, the <resources> and <resource> elements are used to describe a resource URI. The complete path name of the resource is generated by concatenating the value of the base attribute in the <resources> element and the value of the path attribute in the <resource> element. In the example below, the resource URIs are:

The sample below shows a <resources> element for each specific URI that you want to use as a function in Project Siena. When you create your own file, you can have multiple <resource> child elements if the base path for each URI is the same as the one in the <resources> element.

Methods associated with a REST resource are described using the <method> element. A <resource> element can have one or more <method> elements as its children. The <method> element basically describes an HTTP protocol method that can be applied to the REST resource. The id attribute in the <method> element is the identifier that is displayed in the list of functions in Project Siena.

Each <method> element has a <request> and <response> element. Parameters to the resource URI are defined with a <param> element which is a child of the <request> element. For example, the list parameter is supplied for the GetFileAndFolderInfo method.

     <resources base="https://api.dropbox.com" siena:authenticationProviderHref="#Dropbox_Auth">
    <resource path="1/metadata/auto/photos">
      <method name="Get" id="GetFileAndFolderInfo" siena:requiresAuthentication="true">
        <request>
          <param name="list" style="Query" required="true" siena:sampleDefault="true" />
        </request>
        <response siena:resultForm="single">
          <representation mediaType="application/json">
            <param name="GetFileAndFolderInfo_Name" type="sienatool:GetFileAndFolderInfo_Root" style="plain" path="" />
          </representation>
        </response>
      </method>
    </resource>
  </resources>
  <resources base="https://api.dropbox.com" siena:authenticationProviderHref="#Dropbox_Auth">
    <resource path="1/media/auto/">
      <method name="Get" id="DisplayImage" siena:requiresAuthentication="true">
        <request>
          <param name="path" style="Query" required="true" siena:sampleDefault="/Photos/i-b858zMh-M.jpg" />
        </request>
        <response siena:resultForm="single">
          <representation mediaType="application/json">
            <param name="DisplayImage_Name" type="sienatool:DisplayImage_Root" style="plain" path="" />
          </representation>
        </response>
      </method>
    </resource>
  </resources>

<siena:authenticationProviders> and <siena:template>

These elements handle the authentication process depending on the authentication method. This example is for Dropbox using OAuth 2.0. This needs a callback url. As your Project Siena app is not a web app and does not have a URL, you need to pass a placeholder URL that is valid.

   
 <siena:authenticationProviders>
    <siena:oauth2 id="Dropbox_Auth">
      <siena:grantType>
        <siena:implicit>
          <siena:endpoints>
            <siena:authorization url="https://www.dropbox.com/1/oauth2/authorize" />
            <siena:callback url="https://fabrikam-prime-oauth.azurewebsites.net/" />
          </siena:endpoints>
          <siena:credentials clientId="[templated]" />
        </siena:implicit>
      </siena:grantType>
      <siena:resourceAuthorization placement="Query" />
    </siena:oauth2>
  </siena:authenticationProviders>
  <siena:template>
    <siena:variable name="Dropbox__ClientID">
      <siena:doc title="Client ID/API Key" />
      <siena:modifyAuth tag="credentials" href="#Dropbox_Auth" attribute="clientId" />
    </siena:variable>
    <siena:variable name="Dropbox__URI">
      <siena:doc title="Redirect URI" />
      <siena:modifyAuth tag="callback" href="#Dropbox_Auth" attribute="url" />
    </siena:variable>
  </siena:template>

Extensions and Differences to the WADL standard

Below are any extensions that Project Siena supports or any parts of the WADL standard that Project Siena doesn't support. The section numbers refer to the sections in the WADL standard itself.

Cross-referencing is not supported (Section 2.1)

Only self-contained WADLs are supported. Section 2.1 of the WADL standard refers to cross-referencing. Project Siena does not support this. All of the types need to be listed inline.

Application support (Section 2.2)

Supported elements: <doc>, <grammars>, <resources>, <method>

Unsupported elements: <representation>, <resource type>

Project Siena Specific Attribute

Required

Description

siena:serviceid

Required

Identifies the name of the service when the WADL is imported into Project Siena

 

siena:author

Optional

 

This is not displayed in Project Siena, but it could be useful to know who created the WADL file

Project Siena Specific Attribute

Required

Description

siena:serviceid

Required

Identifies the name of the service when the WADL is imported into Project Siena

siena:author

 

Optional

This is not displayed in Project Siena, but it could be useful to know who created the WADL file

Documentation (Section 2.3)

This is supported on all nodes in the WADL file, but only the <method> and <siena:function> elements use the <doc> element.

Grammars (Section 2.4)

The WADL file must be self-contained, so the <include> element is not supported.

Project Siena only supports two types of elements for <grammars>: <siena:sampleXmlTypes> and <siena:jsonTypes>.

Resources (Section 2.5)

A new attribute is supported: siena:authenticationProviderhref.

Resource (Section 2.6)

Child elements: <doc>, <method>, <param> (supported attributes: template / unsupported attributes: matrix, query, header)

Supported attributes: path

Unsupported attributes: id, type, queryType

Project Siena specific additional attributes: siena: authenticationProviderHref, siena: additionalParameters

Resource Type (Section 2.7)

Resource type is not currently supported.

Method (Section 2.8)

Supported child elements: <doc> (optional), <request> (optional), <response> (optional)

Supported attributes:

  • Name - this is the HTTP method (PUT, GET, POST, DELETE and PATCH are supported)

  • id is supported. Project Siena requires this id for locally defined methods. This is the default name for the function for the method.

Project Siena specific attribute

Required

Description

siena:requiresAuthentication

Optional

  

Indicates the method needs authentication - the default is false

 

siena:disableTryIt

Optional

 

Disables the Try It button for this function in Project Siena

Request (Section 2.9)

Supported child elements: <doc> (optional), <representation> (optional), <param> (optional) - supports query and header

Extensions for Project Siena: siena:additionalParameters

Response (Section 2.10)

Supported child elements: <doc> (optional), <representation> (zero or one)

Unsupported child element: <param>

Unsupported attributes: status

Project Siena extensions: resultform attribute

Representation (Section 2.11)

For Project Siena there are differences between the <representation> element as a child of the <request> or <response> element.

For <representation> as a child of either request or response:

Supported child element: <doc> (optional)

Unsupported child elements and attributes: <representation> reference element, id attribute, profile attribute

For <representation> as a child of request:

Supported MediaTypes: application/json, application/x-www-form-urlencoded, multipart/form-data

Unsupported attributes: element

For <representation> as a child of response:

Supported MediaTypes: application/json, application/xml, image ( equivalent to image/*), audio ( equivalent to audio/*)

Only application/json and application/xml support child <param> elements.

The <representation> element as a child of the <response> element is only supported when the siena:resultform attribute for the response has a value of either single or aggregate.

Parameter (Section 2.12)

Parameter refers to the <param> element.

Supported as a child of these elements: <request>, <resource>, <representation>

Not supported as a child of these elements: <parameter reference>, <application>, <response>

Supported attributes: name, style, type, path, required, fixed, default (as the parameter default and not the server default)

Unsupported attributes: id, repeating

Supported values for the style attribute of the <param> element:

Value

Parent element of <param>

Usage

header

<request>

  

Specifies an HTTP header for the HTTP request.

 

query

<request>

 

Specifies a URI query parameter based on the rules for the media type specified by the queryType attribute.

 

query

<representation>

 

Specifies a component of the representation as a name value pair formatted according to the rules of the media type. (Typically used with these media types: application/x-www-form-urlencoded, multipart/form-data.)

 

template

<resource>

 

The parameter is represented as a string encoding of the parameter value and is substituted into the value of the path attribute of the resource element

 

plain

<representation>

 

Specifies a component of the representation formatted as a string encoding of the parameter value according to the rules of the media type.

Option (Section 2.12.3)

The <option> element can be used to supply the possible values for <param> elements that are used as parameters for functions in Project Siena. This element is then used for IntelliSense in Project Siena.

Link (Section 2.12.4)

This is not supported for Project Siena.

Extensions for Project Siena

siena: additionalParameters

This element defines an additional parameter that can be used with all functions in Project Siena. This is supported for <resource> and <request> elements only.

siena: resultForm

This lets you create a WADL that is easier for others to use by adding rules for the return values for methods and functions. This is only supported for <response> elements.

These types of variables are supported:

Variable

Description

void

  

Project Siena ignores the returned response but checks it is successful

 

self

Returns the body of the response based on the media type

single

Returns the value identified by the single <param>

aggregate

Returns a record for each <param> with key value pairs

siena: authenticationProviderhref

Identifies the authentication provider used for the resource or method. This is supported by the <resources> and <resource> elements. Two types of authentication providers are supported: OAuth1 and OAuth2. See the Dropbox OAuth2 sample.

siena: function

This supports custom functions. It takes the user supplied information and passes this to the REST API.

Load a WADL file and access the data

  1. Click App Data, then click Data Sources.

  2. Under Add new source, click REST.

  3. Click Choose your configuration file to select the location of your WADL file and click Open to load the file.

  4. The data source is now displayed. You can select the functions and click Try it to check that the correct data is returned.

  5. Access the data from your app with a gallery. Choose the gallery that you want.

  6. Choose Data and then Items to use the data source that you just added. Use this syntax to access the data: <data source name>!<function name>()!elements (for example: CourseraREST!GetCourses()!elements). Project Siena makes this easy by helping you with the syntax.

    Enter the syntax for the function to access the data from your REST API service in the gallery

    Project Siena tries to guess which fields from your data you want to use in the gallery. If these choices are not correct, or a warning icon is shown, you can manually choose which fields to display.

    Choose the Pick Column to Display icon to select different the data you want to show in each field

    Now you have the data from your REST API service displayed in your app.

If your REST API service uses OAuth authentication, the username and password are not stored in your app. The user must enter a valid username and password for the service to authorize their access. An authorization token is normally valid for a specific period of time for a service. The user will be prompted if it has expired to re-enter a valid username and password.

Q & A

Q: How can I use the value of another field when I access data from REST APIs?

A: In the expression for Items, pass the value of that field into the function that calls the REST API. For example, to show the photo for the course use the value from the gallery that displays all the courses. Then as you move through the gallery, the correct photo is shown.

Choose Items; select the data source; add the value of a field as the parameter