If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

Introduction

You can use REST services to integrate backend cloud services that support RESTful APIs. Like any other service, REST services usually have inputs and outputs, and must be set up within Appery.io.

Creating a service consists of:

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

Note: You can use any service that’s exposed as a REST API.

Quickstart

If you’re new to Appery.io, please try these step-by-step tutorials:

Note: We have many other tutorials on using 3rd party APIs.

Create a new service

To create a new service, from Project view, select Create New > Service. Enter a service name and click “Create Service”:

rest_new_service

The service opens in a new tab that has the following views:

Settings – define the main options for the service:

rest_settings

Request – add request headers (Headers tab), input parameters (Query String tab), and set default values, if needed:

rest_request_headers

Response – define output headers (Headers tab) and parameters (Body tab):

rest_content_length

Test – test the service, and create a service response based on the test results:

rest_test

Echo – get data from the service without invoking it:

rest_echo

Settings view allows you to set the:

  • Name – a service name.
  • URL – service URL which allows access to public (without authorization) or private (requires authorization) data. Read about using dynamic URLs.
  • Method – type of request:
    • Get – requests data from a specified resource.
    • Post – submits data to be processed to a specified resource.
    • Put – uploads the specified data (a complete replacement of data).
    • Patch – updates data (applies partial modifications to a resource).
    • Delete – deletes data from the specified resource.
  • Data Type – format of the data returned by the service:
    • JSON – JavaScript Object Notation: text-based open standard, designed for human-readable data exchange between the browser and server.
    • JSONP- JSON with padding: provides a method to request data from a server in a different domain.
    • XML – Extensible Markup Language: a set of rules for encoding documents in a format that is both human-readable and machine-readable.
  • Settings – the settings service can be selected from the drop-down list.
  • Security Context – a generic security service running JavaScript code before or after the REST service execution.
  • Content Type – when you use the POST, PATCH, and PUT methods, you can specify how the data should be encoded when submitting it to the server. A list of name/value pairs depends on the value you set to this parameter:
    • JSON: application/json application/javascript text/javascript
    • XML: application/xml text/xml application/xhtml+xml application/atom+xml
    • x-www-form-urlencoded: application/x-www-form-urlencoded
    • data: application/octet-stream
  • Appery.io Proxy – if your service doesn’t support cross-domain calls, you can check this box to provide a proxy service that works for testing.

Note: View more information about the Appery.io Proxy service via the link.

Add the service to a page

Once a service has been defined, it can be added and mapped to one or more pages. To add a service to a page:

  • Go to page where you need to use this service.
  • Switch to Data view by clicking the Data tab.
  • Add a datasource, select “Service,” and then the service you’ve created:

rest_chose_datasoruce

  • Click the “Add” button. A service instance is added to the page:

rest_added_datasource

By default, the service instance is named restserviceX. You can change it to a more meaningful name by setting its name property.

Request parameters

Request view allows you to define the request parameters and headers required by the service to be invoked. Every service can define a different number of request parameters. Some parameters are required; others may be optional. Some services don’t require any request parameters at all.

To create, edit, or delete request parameters, open Request view and switch to Query String tab.

Query parameters

To create a new parameter, enter its name and click “Add”:

rest_add_request_parameter

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

rest_two_req_parameters_with_values

When you use the service on a page, you can use the default values, or you can map page component properties to the parameters instead.

An example using one default and one mapped request parameter:

rest_two_req_parameters_with_value_and_mapping

Note: Mapping is described here.

Import query string

You can add a set of request parameters by importing query string. To do this, click “Import” and enter a query string in the newly-appeared window:

rest_import_query_string

Click “Import” to add request parameters based on the provided data.  The imported query string should be composed as a series of field-value pairs as in the following:

Request headers

Some services require one or more request parameters to be sent as Header. Header parameters should be added on the Request > Headers tab:

rest_header_parameter

Import request headers

You can add a set of request headers at once by using Import feature. Headers should be specified as field-value pairs. Use line break as separator between pairs as following:

Here is how it looks from the Appery.io builder:

rest_import_headers

Request body

When you use POST, PUT or PATCH methods, the new Body tab appears in Request view. Its type is based on the Content Type chosen in the REST Service settings. If Content Type is set to Data, the Request Body contains a single parameter which you can’t modify:

app_data_parameter

When adding the service to a page, you can map binary data (e.g. files) to this parameter.

Default request parameters value

You are not required to map every service input parameter to an element on the page. It’s possible to set a default value for an input parameter.

Simply enter any value:

rest_input_value_fixed

You can also use JavaScript to provide a default value. Click “JS” and provide a default value or expression that will calculate value:

Return fixed value:

Return current day of month:

Return value from the Input component entered by user:

Note: Read here about Appery.io JavaScript API.

If you set default values during service creation:

rest_fixed_values_during_creation

Then those values automatically copied to the service instance mapping:

rest_fixed_values_during_creation_mapping

Response parameters

Response view allows you to define the response parameters that the service returns. Response view consists of two tabs – Headers and Body. The Headers tab contain headers that should be returned in the service response. The Body tab contains all other response data. Services may return data in JSON, JSONP or XML format. You can set the return data form in Settings view.

To define response parameters manually, open Response view and switch to the Body tab. First, you need to choose the type for the response root element. It can be type of Object or an Array. You can’t remove the response root element. Choose Array if your service should return an array (for example, list of customers) or choose Object if your service should return single set of data (for example, information about certain customer):

rest_response_root_element_type

To add a response parameter, enter the output parameter’s name, and click “Add.” The parameter appears in the list:

rest_response_parameter

In the case of using an Array type for response root element, there are two parameters that can’t be removed: $ – the array itself and $[i] – each value of array (see Mapping for more about this):

rest_response_array

Response parameters and array elements ($[i]) can be type of all possible JSON types:

rest_response_parameter_types

This is how to specify the service response as an array of numbers:

rest_response_array_of_numbers

You can create more complex response structures to fit your needs. Here is how to specify the response of the hypothetical customer List service:

rest_response_customer_structure

In the example above, there is the root element ($) type of array, which means that the defined structure can be repeated multiple times (for every customer). $[i] – is a reference to every array element and it can be used further for mapping purposes. Next, there are several fields with different data types that correspond to field types stored in the database.

Note: This tutorial shows how to bind an array by mapping to a List component.

Import response headers

Response headers can be imported the same way as request headers. Open Response > Headers and click “Import.” Provide headers composed as field-value pairs and divide them with a line break like the following:

Import response body

You can add a set of response parameters by importing JSON (for JSON or JSONP Data Type specified in the service Settings) or XML (for XML Data Type). Go to Response > Body and click “Import.” Use the following syntax for JSON or JSONP Data Types:

Use the following syntax for XML Data Type:

Automatically define response

You can define response parameters automatically when testing the service (in Test view). Once you’ve defined the service properties, and defined one or more request parameters, you can quickly test the service to make sure it works and returns a valid response. Defining the response manually can become a time consuming and error-prone process; very often the service returns a lot of data. It’s possible to create the response automatically after testing the service.

To test the service and create a response, follow these steps:

1. Switch to Test view.

2. Enter values for the request parameters. If you set the default values, you can see them.

3. Click “Test.” The service is invoked and the result will appear in the “Response” area:

rest_customers_test

4. Click “Import as Response.” The service response parameters will be created based on the returned data.

5. Switch to Response > Body view to see the generated response.

Incorrect format error

You can get the following “incorrect format error message” when trying to create the response: Incorrect format. Please verify sample response data and try again. The first thing you should do is check whether the format is valid. A good way to check is by using the JSON Validator http://jsonlint.com or XML validation http://www.xmlvalidation.com/. If the JSON is valid, copy the data from http://jsonlint.com window, paste it into service editor (Response > Create from Sample Response), and try it again.

Service testing

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

To test the service:

1. Switch to Test view.

2. Enter some values for request parameters. If you set default values, you can see them.

3. Click “Test.” The service is invoked and the result appears in the Response area:

rest_customers_test

Using Echo

In Echo view, you can enable the Echo service, which allows you to get data from a service without invoking it. It’s like a mock service.

It works by you giving a sample response from a service to Appery.io. When it invokes the service, Appery.io uses this (static) sample, instead of actually invoking the service.

To enable the Echo service:

1. Switch to Echo view, and check the “Enable Echo” box.

2. Paste a sample service response:

rest_echo_on

Note: Be sure to turn off the 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 string which contains data in a corresponding format (JSON, XML) in run time:

To turn Echo off:

Parameters in URL (Dynamic URL)

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

or:

Where the id would be set when the service is invoked. In this case, id would need to be defined as a request parameter.

Also, id can be specified in the Settings file.

Settings can be used for dynamic URLs in RESTs. For more information, go here.

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

Header parameters are not used for service request URL.

Alternatively, the URL with dynamic parameter can be passed under the Settings tab of the particular REST service:

The parameter id, when added under the REST service Query String tab:ID

Or passed in the first level under Body on theRequest tab:

Substituted parameters will not be added to the URL, but will replace the corresponding URL parameter instead.

The parameters substituted aren’t included into the request.

Escaping special characters in URL

It is good practice to avoid using the special characters when formulating a URI string. In case you need to pass the characters below, the corresponding escape characters must be used instead, so when the browser parses your code it will not misinterpret the link:

Character Escape Character Character Escape Character
Space %20 # %23
$ %24 % %25
& %26 @ %40
` %60 / %2F
: %3A ; %3B
< %3C = %3D
> %3E ? %3F
[ %5B \ %5C
] %5D ^ %5E
{ %7B | %7C
} %7D ~ %7E
%22 %27
+ %2B , %2C

Invocation order

By default, services are invoked in asynchronous order. Let’s say there is “Service A,” and “Service B,” and both are invoked in order on button click:

  1. Service A.
  2. Service B.

There is no guarantee that “Service A” will finish before “Service B” is invoked. When “Service A” is invoked, the execution then moves to “Service B.” If you need to ensure that “Service B” is only invoked after “Service A” is finished, then use a “Service A” Success event to invoke “Service B.”

Invoking from JavaScript

To invoke any service directly from JavaScript, use:

serviceInstanceName – is the name of the service instance from DATA view.

For instance, you have a datasource get_instruments:
get_instruments

Use following JavaScript code to invoke the service:

Passing parameters

You can also pass a request parameters and header request parameters when invoking via JavaScript by using following syntax:

Here is how you can pass a where parameter to get_instruments service :

Basic authentication

  • Add the following as an external resource in Project > App profile > External resources:

  • You may also add this as a JavaScript file by simply copying the entire content of the file.
  • Create the following JavaScript file (note that username:password needs to be a string):

  • Create the service.
  • Add an Authorization request header.
  • Add the service to the page.
  • Open service Before send mapping.
  • For Authorization parameter, click “JS” and enter the following JavaScript:

You can now test the service on the page.

Testing the service

  • Run the service once as described below.
  • Use Chrome Developer Tools (or Firebug), open the Network tab and view the request headers sent. You’ll see something like:
  • You can now take the Authorization value (Basic a2lkURA2NzpkNmYxOTQ2ZUWXMzI0YzhkYTabNjNjMGNkMTMzNzUxNA==) and use it as a request parameter for the service:

rest_basic_auth