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

See the Appery.io database REST API reference.

Introduction

Appery.io provides a cloud database to store app data, such as customers, orders, locations, etc. Your app communicates with this cloud database via an elegantly simple REST API.

The database web console is used to manage all aspects of the databases, view and edit the data, run queries, and more.

Currently, Appery.io uses MongoDB: 2.6.8-1.

Quickstart

If you’re new to the Appery.io database, try this tutorial for jQuery Mobile projects: building your first mobile app with a database.

Accessing the web console

The Appery.io database allows you to manage your database via the web interface. To access this console, go to the Databases tab:

On this page, you can:

  • Create a new database.
  • View the list of existing databases.
  • Open and edit the existing databases.
  • View statistics and reports for your databases.
  • Manage the session token lifetime.

The Databases page appears empty if you subscription expires (Subscription status: “Your subscription has expired”). To regain access to your databases, sign in any time and purchase a paid plan (or renew your suspended plan payment).

Working with databases

To create a new database, click “Create new database.” If the database is already created, click “Open” to start working with it.

Database collections

The term Collection in Appery.io databases corresponds to the term Table in SQL databases.

When you open the database, the Collections view opens. Here you can:

  • Create and import collections.
  • Edit collections (add and delete columns and rows), change permissions, and rename or delete collections.
  • Manage indexes and change default ACLs.
  • See REST APIs for every collection, including the predefined collections.
  • Add users and set passwords in the Users collection.
  • Upload and download files in the Files collection.
  • Add devices with installed apps in the Devices collection.

Predefined collections

There are three predefined collections in every database:

  1. Users.
  2. Files.
  3. Devices.

The Users collection includes the following predefined fields:

  • _id – identification number; consists of letters and numbers, it cannot be changed.
  • username – username that may be used in your project to get access to the database.
  • password – password is hidden.
  • acl – permissions for the user to access the database.
  • _createdAt – date and time the user was created.
  • _updatedAt – date and time the user’s data was last updated.

You can add custom columns to the Users collection.

The Files collection includes the following predefined fields:

  • File Name – file name created by Appery.io.
  • Original File Name – the name of the file uploaded to the database.
  • Size – file size.
  • Content-Type – file type. This information is based on the file format.
  • _createdAt – date and time of file upload.
  • Owner – displayed only when the file was created directly from a POST request. This field has also an “Info” icon. Upon clicking the icon, a popup appears with information about the file owner.
  • acl – permissions for the user to access the database.

The Devices collection displays devices with installed apps connected to this database. This collection includes the following predefined fields:

  • _id
  • deviceID
  • token
  • type
  • channels
  • timeZone
  • acl
  • _createdAt – date and time the device was created.
  • _updatedAt – date and time the device was last updated.

You can add custom columns to the Devices collection.

Custom collections

To create a collection, click “Create new collection,” enter the new collection name, and confirm the action: a new collection has the following predefined columns:

  • _id
  • acl
  • _createdAt
  • _updatedAt

You can do the following operations with collections:

  • Rename the collection – click “Rename” and enter the new collection name.
  • Delete the collection – click “Delete” and confirm your action.
  • Change permissions on working with data – click “Security and Permissions” to allow or forbid reading and/or writing of data or securing the collection.
  • Manage indexes – click “Manage indexes to add or remove indexes for the current collection. Indexes provide high-performance read operations for frequently used queries. Check “Unique” to mark the index as unique. Use drag&drop to change column order.

Read more about MongoDB indexes to properly understand this concept.

  • Change default ACL – click “Change default ACL” to manage the Access Control List.
    Click on the Username placeholder, and you’ll see the drop-down list with all existing users:

Select the needed user, and click “Add User” to manage the user’s access rights.

Select All users * to manage access rights for all users or select @Creator to manage access rights for the user that created the current object. The most common use case for @Creator is when @Creator has rights to read and write and All users * only has read rights. So, only the object creator can modify it.

If you’re using automatically-imported Create or Update REST Services, remove the acl object from the REST Service Request. Otherwise, acl sent with a REST Service will overwrite the default acl.

  • Add column – click “+Col” and enter the column name and data type. You can check the “Indexed column” box, if you want the column data to be indexed:

For more information, see data types.

  • Remove column – click “-Col” and select the column from the drop-down list of columns you created. You cannot remove predefined columns.
  • Edit column name – click “Edit col” to select the column from the drop-down list of custom columns, and enter a new name for the column. You can also check or uncheck the “Indexed column” box.
  • Add data – click “+Row” and enter the data into the appropriate fields.
  • Remove selected data – check the rows you need to be removed and click “-Row”. If the table has empty rows (added but not filled with data), those rows will also be removed. If no row is selected, nothing will be removed, including empty rows.
  • Remove all data – click “Delete all”, and confirm your action to remove all data from the collection.
  • Import data – import your files with adding to or replacing the existing data.
  • Watch data in full screen mode – click “Full Screen”.
  • Refresh data – click “Refresh” to see updated data in the collection.

Secure collections

By default, the Secure collection option is disabled. The data of these collections can be retrieved via REST services, without the need to provide a sessionToken. By turning on the Secure collection option (you can find this option under the Security and permissions tab), any action with collections via REST services should be done with the provided sessionToken parameter. This means that only logged-in users can read these collections.

Read more about login services via the link.

Import collection

You can import a collection if you have a .json or .csv file. To import a collection, click “Import a collection,” enter the collection name, and select the file to be imported. Please see the sample files format below.

.json

.csv

REST (cURL command)

The REST or curl command section is used to show examples for commands which are supported by the Appery.io database. The list of commands may differ depending on the collection. The REST commands for the Users collection are shown below:
REST

cURL command example:

Run query

Here you can also run queries for a quick test. To do this click the toggle right to the Query label, and you’ll see an input field and a Run query button. Clicking the Run query button will execute the GET service to the selected collection (which is opened right now). For testing purposes only,  the first 10 records will be displayed. The entered text will be add to a where clause, for example, Cities collection:

name location
string Geopoint
Munich [48.143, 11.574]
Athens [37.985, 23.729]
Amsterdam [52.373, 4.895]

To return cities with the name Munich enter {"name":"Munich"} and run query.

You can use all possible queries here, they are described in our database REST API doc.

Social connections

To authenticate users, using social networks can be useful.

To configure signing into your app with a social network like Facebook, Twitter, or Google, go to Database > Your database > Social connections, turn the toggle on for the needed social network, and specify the needed credentials.

Read more on Social network login API.

Versions

Database versions allow storing the current database state. All the settings and data will be saved. You can specify a comment for a specific version. Open the Versions tab and click “New Version” to create a database version. It will be listed below.

You can restore a database to a certain version or delete a version from the list. Restoring the database to a certain version will restore all data and settings that were in the database at the version creation time.

Permissions

On the Permissions tab, you can specify the access permissions (View, Edit or Delete) you give the users of your team.

Only your team users may access your resources. Information on how to enable or change the permission options for them can be found here.

The user the database was shared with will see it from the the Databases list.

The user the database was shared with can open it to view, edit, delete, or clone it (if granted such rights).

Editing the shared database will cause the original database to change. To edit the shared database without affecting its original, use Clone (under the Settings tab) to make a unique copy of it.

Database settings

The Database Settings view allows you to:

  • Check, and manage your Database ID and Master Key.
  • Share your database with other people.
  • Rename, delete, clone your database, or export it to JSON and CSV.
  • Check and manage the session expiration period.
  • Check if the database is used for push notifications.

The API Key is always used when making requests to the REST API. It is added as an X-Appery-Database-Id header.

For additional security, Appery.io provides creation of multiple database API keys. If needed, separate users can be given separate API keys to your database. So, if you need to deny one of the users access to your database you can delete his key.

The Master Key gives you full access to your data. This is root access. It is added as an X-Appery-Master-Key header. Don’t use this key unless you need full access to your data. You can also reset the Master Key to a new value by clicking “Reset.”

The section “Share with support” is placed at the bottom of the page. When a user enables sharing (turns the toggle “on”), the specified resource appears in the admin section. This feature can be used by the support team for viewing and accessing all resources (apps, databases, server scripts, etc) shared.

Statistics

The Statistics pane displays the number of API requests for your databases by month and by day, stored data amount, and number of existing versions. Switching to the Reports pane allows you to review the reports of your collection usage. Apply filters to receive specific reports.

Import database services

Introduction

You can quickly and easily generate services automatically in the Appery.io builder. Click the “CREATE NEW” button in the left of the screen. Choose Database Services in the drop-down menu. You’ll see a popup where you can choose the databases and services you want to import.

After you click “Import selected services,” all of the services will be imported, and shown in a project tree under Services folder. All the necessary fields are already created when you importing the service.

Here is the list of services available for import:

  • Settings service – by default, database settings service contains two parameters: database_url and database_id. They can be used in REST services, and you don’t need to input your database URL or ID manually. In any service’s Settings tab, choose <database_name>_settings in the Settings field.
  • Sign-up service - the sign-up service is used to create a new user in the database.
  • Login service – for existing users, there is a Login service. To log in to the database, provide the user’s username and password. Response contains _id and sessionToken parameters.
  • Logout service – a logout service needs a sessionToken, which was retrieved upon log in (or sign up). There is no response after the logout procedure.
  • Create service – this service allows you to create new objects.
  • Delete service – You can delete objects as easily as you can create them. The imported delete_service will help you. There is no response after the object has been deleted.
  • List service – the imported list_service is a simple GET command, which lists the collection content.
  • Read service – you can use this service to read a specific object.
  • Update service – this imported service can be used to update objects.
  • Query service – allow you to use queries on your database.

You can find the REST API reference on services described above here.

More help resources

More help resources are links to the blog, our YouTube channel and other web sites.