REST Services

Introduction

You can use REST services to integrate with back-end cloud services that support a RESTful API. Like any service, REST services usually have inputs and outputs and these must be setup within Tiggzi. Follow the links below to learn how to setup a REST service to use in a mobile app. In general, creating a service consists of the following three main steps:

1. Entering service URL
2. Defining the request parameters (the input)
3. Defining the response parameters (the output)

Once you are done reading on how to create a service, learn how to use a service on a page.

Creating a new service

To create a new service, Project view > Create New > Service. Enter a service name and click Create.

When a service is created, you will get the following options:

Name	Description
Name	Service name
URL	Service URL For example: http://search.twitter.com/search.json
Method	Type of request: get post push delete
Data type	What is the format of the data returned by the service (json, jsonp, xml). Here is a good article that describes how JSONP works. json jsonp xml
Content Type	If Method selected is post or delete, then body content can be set to: json xml x-www-form-urlencoded
Security Context	Select a security service (rarely used)
Tiggzi Proxy	Enable if your service doesn’t support cross-domain calls. More information.

Defining request parameters

For a service to be invoked, it usually requires request parameters. Every service will define a different number of request parameters. For example, for the Twitter search service to work (http://search.twitter.com/search.json?q=), it requires a parameter named q (there are many optional parameters as well). Some services don’t require any request parameters.

To create, edit, or delete the request parameters, open the Request Parameters tab. To create a new parameter, enter its name and click the green Add button.

If a service request parameter value doesn’t change, you can set its default value. For example, the following shows two parameters set to default values:

When you use the service on a page, you can use the default values or map page component properties to the parameters instead. For example (using one default and one mapped):

Header request parameters

Many services require one or more request parameters to be sent as Header. To mark a parameter as Header, simply check the Header check box for it.

Defining Response Parameters

Every service usually returns some data back, it can be a single value or a whole set of values (array) For example, click on this URL: http://search.twitter.com/search.json?q=html5 to see what Twitter search returns. The response is in JSON format. Some services may return data in XML. You can set the return data form in the Properties tab.

To define response parameters manually, open the Response Parameters tab. Enter one or more output parameter names and click the Add button. The parameter will appear in the list. To mark a parameter to be an array, check the Array check box. To define nodes inside the array, click + button in the Add level column.

For example, the following shows response with two parameters:

The following shows a response with an array:

Automatically defining response parameters

Usually services return a lot of data back which makes defining the response manually a time consuming process and error prone. It’s possible to create the response automatically after testing the service.

1. Open Test Connection tab
2. Any values for request parameters. If you set any default values, you will see them set
3. Click Test. The service will be invoked and the result shown in the area below.
4. Click Automatically Create Service Response button. This will automatically create the service response parameters based on the data return
5. Open Response Parameters to see the generated response.

Testing the service

Once you defined service properties and defined one or more request parameters you can quickly test the service to make sure it works and returns valid response.

First, define the service URL and request parameters

1. Open Test Connection tab
2. Enter values for request parameters. If you set any default values, you will see them set
3. Click Test. You will see service invocation in text area below

Using Echo (service mock)

Enabling Echo service allows you to get data from a service without actually invoking the service. It’s like a mock service. Here is how it works. You give sample response from a service to Tiggzi and when invoking the service, Tiggzi will use this (static) sample,instead of invoking the actual service.

1. To enable Echo service, open Echo Service tab and check Enable Echo
2. Paste a sample service response:

Note: Make sure to turn off Echo service when using the app in production.

Controlling Echo in runtime

You can also control Echo via JavaScript in run time:

You can set it to any JSON in run time like this:

service_instance_name.__requestOptions.echo = {"login":"[email protected]", "password":"abc"};

To turn off echo:

service_instance_name.__requestOptions.echo = '';

Parameters in the URL (dynamic URL)

If you need to configure the URL with dynamic parts, define the service URL with parameters using {}:

http://host/name/edit/{some_id}

or

http://host/name/{some_id}/edit

where the some_id would be set when the service is invoked. In this case some_id would need to be defined as a request parameter.

Any part of the URL can be expanded this way, even the entire URL.

Note: If you specify a request parameter to be header, it will not be expanded into the URL.

Setting up Basic Authentication

1. Add http://crypto-js.googlecode.com/files/2.5.3-crypto-min.js as an external resource in Project > App profile > External resources
   1. You may also add this as JavaScript file by simply copying the entire content of the file.
2. Create the following JavaScript file:

   function getAuth() {
          var bytes = Crypto.charenc.Binary.stringToBytes('username:password');
          var base64 = Crypto.util.bytesToBase64(bytes);
          return "Basic " + base64;
       }

   Note that username:password need to be a string

3. Create the service
4. Add Authorization request parameter and mark it as Header.
5. Add the service to the page
6. Open service mapping
7. For this parameter, click Add… and enter the following JavaScript:

   return getAuth();

You can now test the service on the page.

Testing a service

1. Run the service once as described below.
2. Use Chrome Developer Tools (or Firebug), open Network tab and view the request headers sent. You will see something like this:

   Authorization: Basic a2lkURA2NzpkNmYxOTQ2ZUWXMzI0YzhkYTabNjNjMGNkMTMzNzUxNA==

3. You can now take the Authorization value (Basic a2lkURA2NzpkNmYxOTQ2ZUWXMzI0YzhkYTabNjNjMGNkMTMzNzUxNA==) and use it as request parameter for the service:
   

Understanding JSON, JSONP, and Tiggzi Proxy

Understanding JSON, JSONP, and Tiggzi Proxy