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).

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

Create a new service

To create a new service, from the Project view, select CREATE NEW > Service. Enter a service name and click Create Service.

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

The 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.
  • Response 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 – it is possible to store the parameters into Settings service and then use them in REST service URL. Read here for more.
  • Security Context (Not supported in beta) – a generic security service running JavaScript code before or after the REST service execution.
  • Use 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.

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

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

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

Echo – get data from the service without invoking it:Echo

Invoking the service

Once a service has been defined, it can be invoked from any page. To invoke the service:

  • Go to the page where you need to use this service.
  • Switch to SCOPE by clicking the SCOPE tab.
  • Click Edit next the function where you want to call the service.
  • To invoke a service, in the function editor snippet panel, select Invoke service, from the snippets drop-down list.
  • A default service name is selected. Click CTRL+SPACE to autocomplete a service name.
  • An autogenerated code is added to the function.
  • You can call mapping GUI from the functions editor in the screen SCOPE tab. Click Mapping to set service mapping, if needed.
  • The mapping editor is opened on Mapping button click.
  • When you click Save & Replace, the generated mapping code is added to the JavaScript code in the editor where you can change it as you need.

Please note you will have to recreate the whole mapping if you click “Mapping” button again.

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 the Request view and switch to the Query String tab.

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 the Settings view.

To define response parameters manually, open the 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, Array or any custom type created in Model. 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):

To add a response parameter, enter the output parameter’s name, and click Add.

You can create complex response structures to fit your needs.

Testing the service

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 the 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.

Automatically define response

You can define response parameters automatically when testing the service (in the 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 the 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.

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

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

Using Echo

In the 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 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 the Echo view, and check the Enable Echo box:
EnableEcho

2. Paste a sample service response.

Be sure to turn off the Echo service when using the app in production.

Parameters in URL (Dynamic URL)

Dynamic URLs are very common in any mobile app. When building AngularJS apps with Appery.io there are a few ways to make parts of the URL (or even the entire URL) dynamic. For example, you have the following URL, where the {id} part should be dynamic:

  1. First of all, you can use the Settings service to perform dynamic substitutions:
    1.  Create a new Settings service (if you don’t have one yet) by going to CREATE NEW > Service > Settings (REST settings).
    2. Then, create a new id parameter in the newly-created Settings and provide a value for it.
    3. Now, go to your REST service, and change the dynamic part of your URL to {MySettings.id} where MySettings is the settings service name, and id is the name of the parameter. Your URL should look like:

    You can use the Settings service to substitute values in the URL, headers, query values and body values.

  2. Alternatively, you can create request parameters directly in the REST service. They will be automatically substituted if names coincide. You can use this approach if you need visual Mapping for dynamic parameters:
    1. Go to your REST service Request > Query String.
    2. Create the new id parameter and provide a value for it.
    3. Change the REST service URL to http://mywebsite.com/name/{id}/edit.
    4. Because the value of the id parameter will be automatically inserted to the {id} placeholder, it won’t be added to the end of the URL as a query string.

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

Header parameters are not used for service request URL.

Escaping special characters in the 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