Client Services

A client REST service is an imported service from Create new > Backend Services that integrates the app with Appery.io backend services or external REST APIs:

• API Express.
• Database.
• Server Code.

To learn more about API integrations go to Using APIs in an App page. The rest of this section will cover using and editing an imported service in an app.

Settings

The Settings view allows you to set the:

• Name – a service name.
• URL – service URL to an Appery.io backend service.
• 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 more here.
• Security Context (not supported in Beta) - a generic security service running JavaScript code before or after the REST service execution.

Request

Add request headers (Headers tab), input parameters (Query String tab), and set default values, if needed.

Response

Define output headers (Headers tab) and parameters (Body tab)

Test

To test the service and create a service response based on the test results.

Echo tab

To get data from the service without invoking it.

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 the SCOPE tab.
• Click Edit next to 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.

📘

Note

In older libraries version (1.0, 1.1) EntityAPI is used to create whole request object with default values so all parameters are sent in request (even those you don't want to send).
In new libraries version (1.2 and higher) only filled request fields are sent to server so to send empty values to server you should add mapping/JS code with desirable value or add JS code to create whole request object with EntityAPI.

Request Parameters

Request view allows defining 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 the Query String tab.

Response Parameters

The response view allows defining the response parameters that the service returns. Response view consists of two tabs – Headers and Body. The Headers tab contains 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 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 the single set of data (for example, information about the 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 theTestview). 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.
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 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 the Echo view and check the Enable Echo box. Paste a sample service response.

🚧

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

Parameters in 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:

http://mywebsite.com/name/{id}/edit

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. Create a new id parameter in the newly-created Settings and provide a value for it.
3. 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:

http://mywebsite.com/name/{MySettings.id}/edit

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.

📘

Substituting Values in a URL.

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

• 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

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.

Settings Service

Introduction

The Settings service allows saving app information (such as API keys and URLs) into a settings file, and then reference the data from anywhere in the app. This also allows making changes in one place, rather than having to replace the same value everywhere in the app.

Creating a Settings Service

By default, there is a Settings service added to your app. To create a new Settings service, from the Project view go to: CREATE NEW > Service, check Settings (REST Settings), and click Create Service.
To create a parameter, enter its name and click Add.
It’s basically a properties file with key/value entries. You can also specify an optional description.

Using Settings Service for Dynamic Values in REST Services

A Settings service can be used for making values in a REST service and URLs dynamic. For example, you can have the following URL, where the same part should be a dynamic (should be substituted from the Settings service):
http://mywebsite.com/name/{SettingsName.parameterName}/edit

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 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 {SettingsName.parameterName} where SettingsName is the settings service name, and parameterName is the name of the parameter. Your URL should look like:
   http://mywebsite.com/name/{SettingsName.parameterName}/edit

You can use the Settings service to substitute values in the URL, headers, query values, and body values. For example, if you want to dynamically substitute a parameter in the body of the POST request:

1. Open your REST service and go to Request > Body. Right to the parameter you need (for instance, appId) type {MySettings.appId}.
2. Go to your Settings service or create one if you don’t have one. Create an appId parameter, and provide a value for it.
3. Make sure your Settings service has exactly the same name that you specified in the request body (MySettings in this example).
   You can also change the Settings service parameter values via JavaScript.

Using the Settings Values in JavaScript

Settings service also supports JavaScript API which can be used to read from or write to in the Settings service.

📘

Note

The use of the methods listed below have been deprecated:

• Apperyio.config().
• Apperyio.configAdd().
• Apperyio.getAll().
• Apperyio.init().
• Apperyio.remove().
  These methods have been removed and replaced by their equivalents inside Apperyio.Config. Using the deprecated methods with v1.1 libraries will result in errors.

API methods are listed below.

Apperyio.Config.get( expression [, default_value] )

To retrieve data from settings:

• expression – setting name or expression like SettingsName.database_url.
• default_value – (optional) if settings name or expression can’t be found, then default_value will be returned.
  Returns the value of setting or default_value (if specified).
  Example:

Apperyio.Config.get('MySettings.database_url');

Example:

console.log( Apperyio.Config.get('MySettings.undefined_property', 'default value') );
> default value

Apperyio.Config.add( expression, value )

To add a new key-value to settings:

• expression – setting name or expression such as SettingsName.database_url.
• value – value for a setting.

📘

Note

It can be added for current runtime only, and doesn’t store anything to the app/constants.js file.

Example:

Apperyio.Config.add('MySettings.database_url', 'https://api.appery.io/rest/1/db');

Apperyio.Config.all()

No arguments are needed.
Retrieves all of the available settings as an object.
Example:

Apperyio.Config.all();

Apperyio.Config.init( settings )

• Settings – replace or initialize Config service in the app.
  In general this function shouldn’t be called since it runs at the start of application bootstrapping with all of the settings.
  Example:

Apperyio.Config.init( {
    MySettings: {
        database_url: 'https://api.appery.io/rest/1/db'
    }
} );

Apperyio.Config.remove( expression )

• Expression – setting name or expression like SettingsName.database_url.
  Removes the setting from App settings.

📘

Note

It removes the setting for current runtime only, not from the app/constants.js file.

Example:

console.log( Apperyio.Config.get('MySettings.database_url') );
> https://api.appery.io/rest/1/db
 
Apperyio.Config.remove('MySettings.database_url');
 
console.log( Apperyio.Config.get('MySettings.database_url') );
> undefined

Incompatible Changes

Keep in mind that the controller source code has lost the following:

• $scope.name
• $scope.screenName
• the two code lines below:

var $routeParams = Apperyio.get( "$routeParams" );
$scope.$routeParams = $routeParams;

It might affect the apps performance so make sure you make any of the necessary changes.

Generic Service

Introduction

A Generic service is used to extend the standard REST service. It still has inputs and outputs (as standard service), and can be mapped, but the actual service implementation, or what it does, is entirely up to you. For example, the service can access local browser databases such as IndexedDB or SQLite, or do calculations.

Creating a Generic Service

A Generic service can be created via CREATE NEW > Service > Generic (custom JavaScript implementation).
Default or custom implementation can be opened by clicking Open.
Use a Generic service to provide custom access to data. You can add some custom logic to the automatically generated JavaScript file. If you create a new JavaScript file there’s a default implementation code that can be edited to make your app more flexible and customized.
To call the added service, go to SCOPE and use the snippet Invoke service in the function editor by selecting it from the drop-down.
Сlick Backspace and then CTRL+SPACE to autocomplete a service name. Once the service has been added to the function code, click Mapping to map the service to the page.

📘

Note

Each snippet in the drop-down list has a pop-up with its description and code preview (with syntax highlight) and a link to documentation (if available).

Custom Implementation

Clicking Reset invokes the Add custom implementation option.
Custom implementation can be added by clicking Add custom implementation.
As with the standard REST service, the Generic service also has Request and Response tabs.
They set the general structure of the query although they can be rewritten with any other structure inside implementation code, it’s highly recommended that you follow the structure you’ve specified.
The file of custom JavaScript implementation contains the source code of the generic service. You may change its content following the comments throughout the code.