The Appery.io Developer Hub

Welcome to the Apperyio developer hub. You'll find comprehensive guides and documentation to help you start working with apperyio as quickly as possible, as well as support if you get stuck. Let's jump right in!

log

console.log(format, data1, data2...)

Writes specified data to the trace. If the first argument is a formatted string, the output will be formatted according to it. Data is any of the following types: string, number, boolean, array, and object.

Parameters

Description

format

Optional. If the first argument is a formatted string, the output will be formatted according to it.

distinct

Queries a list of distinct values from a specified collections column.

Parameters

This function has the following parameters:

Argument

Description

Required

dbApiKey

String with database API key.

Yes.

token

String with user token or database Master key.

No.

collectionName

String with database collection name.

Yes.

columnName

String with database column name on which distinct operation will be invoked.

Yes.

queryString

Query to select particular objects on which to invoke the distinct operation. JSON query object that was built in accordance with the Mongo querying documentation.

No.

Examples

This example will retrieve all distinct values from major column. Distinct will return only data from the specified column. In other words, other collection data (columns) are not returned. The Result tab shows information assuming the collection only has English and Chemistry as majors.

The following examples hows how to search by a custom field of Date type. Note that the syntax is slightly different than when using the built-in date columns.

ISO Format

When using one of the built-in data types in a query (_createdAt, _updatedAt), the date value must be formatted in ISO format. When using a custom column with Date type, using ISO format is not required.

This example also includes a user session in the createObject method after user login. If you have enabled ACL for this database collection, and set the default ACL to @Creator, then the ACL column will be automatically filled with the current signed in users ID.

Request with Basic Authentication

This example shows invoking an API that uses Basic Authentication. Basic Authentication usually has this form: http://username@password@host.com. To invoke this from a script add the Authorization header. The username@password encoding can be done using browser's console by running this code: window.btoa("username@password");.

In Memory Data (IMD)

IMD API.

Allows you to store data in fast memory for 20 minutes. It works like a very fast cache. Storing data in the In Memory Data is a lot faster than storing data a database collection. Here are a few examples In Memory Data can be used for:

Storing a temporary token that will expire within 20 minutes.

Storing a temporary password that will expire within 20 minutes.

Any app temporary app data which requires very fast access.

Method summary

Method

Description

put(key, value)

Inserts a specified value with a specified key into In Memory Data (cache). Both key (max. length 64 chars) and value (max. length 255 chars) must be strings.

get(key)

Returns a value specified by a key, or null if the cache contains no such key.

remove(key)

Removes the key/value if such key is present in In Memory Data (cache).

In Memory Data

put

Overview

Push Notifications overview.

Introduction

Appery.io Push Notifications allow you to send notification messages to iOS and Android devices. You can also send targeted messages, for example only to users who subscribed to a particular topic (channel).

X-Appery-Push-API-Key is a required header for this service, you can find this key in the Settings section in Apps > Push Notifications tab. As this is a POST method service, non-header parameters should be passed as request body.

Action Summary

With Appery.io Push Notifications you can perform the following actions:

Send a Push Notification to all or specific devices.

Register a device to receive Push Notifications.

Get device registration information.

Unregister a device. This will unsubscribe a device from receiving messages.

Register Device

Registering a device to receive Push Notification messages.

In order to send a Push Notification message to a device, the device has to register to receive messages. Device registration is done by creating a registration record inside the database Devices built-in collection. Registration is done by making a request to the following endpoint:

deviceId and token information

The deviceId and token parameters are automatically generated device-side. These values can’t be found anywhere except in the devices collection of the Appery.io database. Information about the device (including the deviceId and token parameters) where the app is installed, will be saved in the devices collection of the selected database as soon as the device is running the app.

This service can be used for retrieving information about the device stored in the Devices . The response of this service is JSON, which contains all predefined and user-defined fields of the devices collection. This service can be handy when you need to get the deviceID, check its timeZone, or for any other operation involving device info.

The deviceID can be found in the predefined Devices collection of the Appery.io database.

Note

In the devices collection of the Appery.io database, the deviceID field contains a semicolon. (For libraries 3.0 (JQM) and higher the semicolon is not used.) Replace it with %3B to properly send the request, as shown here:

Update Device

The update device service is for updating information about any device stored in the devices collection. This service can be used for updating any collection field. For example, it can be timeZone, channels or category (which is a user-defined field).

Parameters

The endpoint has the following parameters

Error responses

The endpoint might respond with the following error messages:

HTTP Status

Code

Description

400

PNDU002

App ID not specified

404

PNDU006

Device ID: <deviceId> not found

404

PNDU015

Project GUID: <appId> not found

400

PNDU960

Specified brand is not valid

Example

The following example shows how to update channels column of the specific device. The channels column of the predefined devices collection has an array type. Any new value for this column must be also sent as an array. Any other parameter can be updated the same way.

The X-Appery-App-Id header is a necessary parameter for this request. Other fields are optional. You can specify any field that exists in the devices collection.

Example above will create a new entry in the students collection with marks field type of array.

Pointer

As MongoDB is not a relational database, it can’t perform SQL join operations. Instead, there are pointer types that are used as references to another object. It contains the collection name and _id of the referred-to value. Let’s say that the students collection contains the owner column. That column contains the user ID from the Users collection.

Example

Object

Object type is a general representation of a JSON object, which can have any structure. When an object with object type is given, the column value is specified as a JSON object in { } brackets. Object type also supports querying.

File

File type can be used to store any sort of file. While clicking on the cell with the File type, the Media Manager opens. By clicking “Upload file,” you can choose any file with a non-empty body and size up to 20MB. You can also insert the same file in other rows.

To remove a file from a certain row, click on a cell where it is located and then choose “Reset” in Media Manager.

To remove files from the Media Manager, choose the needed file and click “Delete file.” This operation cannot be undone.

All uploaded files are added to the predefined Files collection. This also works conversely: if the file was added to the predefined Files collection, it will also be available in Media Manager.

Media Manager only contains files related to a database where they have been added.

Security

Security

When you access the Appery.io database via the REST API key, access can be restricted by the ACL. The ACL is formatted as a JSON object where the keys are either object IDs or the special key ** to indicate public access permissions. The values of the ACL are permission objects: JSON objects whose keys are the permission name and a value that is always true.

For example, if you want the user with ID 5278cafce4b01085e4b7945a to have to read-and-write access to an object, as well as make the object publicly readable, the corresponding ACL is:

You can still read and modify ACLs via the REST API, just by accessing the ACL key of an object.For instance, the following example updates the ACL data of one of the tasks. Log in to the database, as shown in signing in.Set up the service as you would for an object update. You need to add the X-Appery-Session-Token, (which you get upon login), and the ACL field with the type of object:

When a new object is created, the following three columns are automatically created: _createdAt, _updatedAt, and _id. These field names are reserved, so you cannot set them yourself. Using the object above, if you did a GET on it, it would look like this, including the reserved fields:

To make it easy to work with collections and objects, you can get the almost-complete curl command for each REST verb. Click on any of the REST verbs (GET, FIND, CREATE, UPDATE, DELETE) to get the curl request.

Number of records

There is a default limit parameter which equals 100. That means that only 100 records will be returned if other wasn’t specified. To avoid this limitation, use the limit parameter in the requests and specify your own value. Max value is 1500.

For more precise examples, documentation below uses Students collection with following structure:

Note

Note

Updating arrays and pointers is also available for the update parameter. If we assume that your collection contains a column user with a pointer type to _users collection, you can update the marks column type of array.

Example

The example will change all of the values in the studentId column to 60.

Batch Operations

Perform several operations in a single API call.

A batch operation performs several API calls in a single call.

Batch API Calls Count

When performing a batch operation, the actual number of API calls is the number of calls inside the batch operation. For example, if a batch operation updates 5 objects, it will count as 5 platform API calls.

Example above means that the returned object must contain {"studentId":50} OR {"studentName":"Dan"}.

Logical AND ($and)

$and performs a logical AND operation on an array of two or more expressions and selects the documents that satisfy all the expressions in the array. The $and operator uses short-circuit evaluation: If the first expression evaluates to false, remaining expressions will not be evaluated:

Examples

Such a query will return only the objects linked to the objects returned by the subquery. In this example, you get an object that has a pointer to the objects with only a High-value in the priority field.

$notInQuery works inversely: the parent query will return the objects not linked to objects returned by the subquery.

How to get all students collection objects, where the owner column doesn’t reference a user named Alice:

It’s also possible to use the $elemMatch operator to match more than one component within an array element. In this case, the array structure must be a little more complex.

The marks column with array of objects:

studentName

studentId

marks

string

number

array

John

10

[{“math”:”5″, “physics”:”7″}]

By using the $elemMatch operator, it’s possible to make a query for each of object fields. Therefore, it’s possible to retrieve all object arrays where the mark for math equals 5, and mark for physics is greater than 6:

Examples

In addition to specifying how many objects to return, you can also specify from which object count to start with the skip parameter. The following example will start at object 6 (skip the first 5) and return (limit) 5 objects.

Retrieving File List

It’s necessary to provide an X-Appery-Session-Token or X-Appery-Master-Key to get the file list. In the case of using the X-Appery-Session-Token file, the list will contain only those files that where uploaded by the current user, or files that were uploaded via the Media Manager, and doesn’t contain default ACL:

If the ACL for the file defines that a certain user doesn’t have read rights, the file will be excluded from the files list:

User

Many mobile apps have the notion of a user -- where each user may sign up for an account in the app, view his or her information, perform actions, and change his or her password. As this functionality is very common, the Appery.io Database comes with a built-in User Management feature. Users are created in the built-in collection called Users, and are managed via the predefined Users collection.

A user object is very similar to any other object you create, with one exception; the user object requires username and password fields. The password field is stored encrypted in the database, and will not be shown in any client request.

Sign In (Login)

A user login will login a user into the backend (database) and return a session token. A session token is then passed with other APIs to do actions on behalf of this user.

Parameter

Required

Description

username

Yes

User username.

password

Yes.

User password.

The sessionToken should be saved to access the user information in subsequent requests. You can save the token in browser's local storage.

Only the sessionToken and _id parameters will be returned in the response after successful authentication. If you want to retrieve custom fields (as email) that were created in Users collection you should send second request after authentication.

To change the sessionToken lifetime, go to Database > Settings and specify session timeout you need.

In addition to the required parameters you can add custom columns and fill them out during user registration.

To reduce the number of errors, the Appery.io database doesn’t allow the creation of new fields from a POST request. First, the fields need to be added in the web console. Once it’s done, you can add a new user with the new field.

Retrieve User Details

/db/users/{userID}

Retrieves information about a user specified by its user ID. Works the same way as Retrieve Current User endpoint by requires the user ID. With this endpoint you can get information about the currently signed in user unless you specify the Master key. With the Master key you can get information about any user in the Users collection.

Examples

This example shows getting information about the currently signed in user:

Example

Sign Out

db/logout

The sign out process will invalidate the user session on the server. This request requires sending the session token which will be invalidated. There is no response for this request in case of success.

Overview

Social Login API.

Introduction

When building an app with Appery.io, you can use social networks to authenticate users. This can be handy: if your app requires registration, instead of providing new credentials, the user can log in with a social network. For now, the following OAuth providers are supported:

Twitter

Facebook

Google

First, you should create your app on the OAuth provider side.

When your app is created, use the provided credentials to configure the connection under database settings: go to Database > Your database > Social connections, turn the toggle on for the needed social network, and specify the needed credentials.

When a user logs in via a social network, a new user will be created in Users collection of the Appery.io database. Appery.io X-Appery-Session-Token will be returned for further API calls.

Invoking Social Network API.

Returned token doesn’t allows to trigger social network providers API. It’s only valid for Appery.io API calls, for example, the Database REST API. In other words, you won't be able to invoke a Facebook API to get a list of your friends. In order to do this, you will need to setup a standard Facebook login functionality.

Parameters

getStatus

Apperyio.User.getStatus()

Returns current login status for certain database. By default, the database which is set by setDefaulDB is used. If you’re making multiple authentication for several databases, you should provide dbId parameter to determine, which database status should be returned.

Overview

jQuery Mobile app JavaScript API.

Appery.io comes with a small JavaScript library to make it easier to select elements in the DOM in a jQuery Mobile app. The library provides a few functions on top of jQuery API to help you select elements and navigate int he app. For any other functions you should use the jQuery API.

jQuery API

It is important that you know how to select elements in the DOM using just the jQuery API.

Find a Component

Apperyio(id)

Apperyio ('component_name') is a shortcut to get a reference to a jQuery Mobile component on a screen by using its designated name. component_name is the name you set in Name property (in Properties panel).

jQuery API

It’s important to familiarize yourself with the jQuery and jQuery Mobile API.

Once you get a reference to an element, you can use the jQuery API to manipulate the element. It is a plain JavaScript and jQuery.

Example

Here is example reading the input field value when clicking a button:

Add a Click event to the button.

Add a Run Custom Java Script action to the Click event.

Add this JavaScript as the custom JavaScript (assuming the Input component name is Input).

Example

Once you get a reference to a component, which part of the jQuery API is available depends on the component. For example, if you get a reference to an Input component, then you could use this to read or set its value: