Would you like to contribute to the Titanium docs? To get started, sign up for an account on the Appcelerator Wiki and sign our CLA.

Skip to end of metadata
Go to start of metadata


Axway API Runtime Services enables you to develop and publish Node.js applications to the cloud. API Runtime Services includes a simple command-line interface and an MVC framework that makes it easy for both novice and experienced Node.js developers to create apps and services. With API Runtime Services, you can:

  • Build custom services to extend the existing ArrowDB services
  • Host your existing Node.js application or service in API Runtime Services
  • Develop an API Runtime Services service for your Titanium apps using the same development language (JavaScript)

This quick start guide will walk you through the process of creating a simple API Runtime Services Chat Room app using the built-in MVC framework.

If you just want to deploy an existing Node.js app, see Standard Node Applications.


To create API Runtime Services applications, you need the Appcelerator CLI.

  1. Download and install Node.js from http://nodejs.org/#download, which includes the npm package manager needed to install the Appcelerator CLI.
  2. From a console window, run the following command to install the CLI: 

  3. After installation, run the setup command to install required components: 

    After the CLI downloads and installs the required components, you will be prompted to login and authorize your computer. The CLI will ask to send an authorization token to your e-mail account or as a text to your mobile phone.  Enter the authorization token once you receive it to complete the registration process.

Create your first API Runtime Services app

1. Login with Appcelerator credentials

To work with API Runtime Services applications, you must authenticate yourself with the ACS cloud. Run the following command: 

Follow the prompts to login to API Runtime Services with your Appcelerator account. If you do not have an Appcelerator account, you can sign up for a free account.

2. Create a new application

To create an application: 

This creates a new application in the MyFirstApp folder. By default, the new application is configured to use the API Runtime Services MVC framework.

3. Publish your application to the cloud

Change working directory to the MyFirstApp directory (the app's root directory), and run the appc cloud publish command to publish the app to the cloud: 

Congratulations! Now you've successfully published your first API Runtime Services app to the cloud!

Open a web browser and enter the URL you get from step #3. You'll get a big welcome from API Runtime Services!

The chat room app

Let's add more features to the app to make it a public chat room. The app will be built using the Arrow Cloud MVC Framework and use the built-in WebSocket server for establishing a connection between the client (web browser) and server, so that each post message can be pushed to all connected clients.

You can just copy and paste the code snippets below into the corresponding project files.

Enough talking, let's start coding!


The controller code is invoked whenever a corresponding HTTP request comes in. All controller files should be placed in controllers directory in the app's project.


This controller will be configured (in config.json) to respond to an HTTP GET request with URL "/", and will return the chatroom web page.

Websocket event handler

The websocket event handler is invoked whenever matching websocket events are received from a client. All websocket event handler files should be placed in the websockets directory inside the application directory.


This event handler will be configured (in config.json) to respond to a certain event to broadcast a received chat message from a client to all other chat clients.


config.json contains configuration sections for route mappings, filters and websocket event handlers. This configuration file binds requests to handlers (functions). 


In this case, config.json defines a route for the GET method on path "/", and binds this route to the function chatroom in application.js; it also defines the function receiveMessage in chatroom.js to be invoked whenever a newChatMsg event is received from a client.


Views are where your user interface (UI) is defined. All views files reside in views directory in the application's project directory. API Runtime Services uses EJS as view engine by default. 


Static files

An API Runtime Services application uses the public directory as the root for static files. You can place static files such as stylesheets, image assets and client-side scripts in that directory. You can create any directory structure you need to under the public directory.


Now let's run the application.

Change to the the working directory to the app's directory and use the appc cloud run command to start the server locally: 

Open a web browser and visit http://localhost:8080 to start chatting. Open a different browser window and type a random message and click send. You will see the message show up in the first window!

Now let's publish the app to API Runtime Services!

First, replace the 'http://localhost:8080' in file /views/chatroom.ejs on line 8 with your app's URL as returned by 'acs publish' command (for example, http://<App_ID>.cloudapp.appcelerator.com). This will set the chat client connection to the server running in the cloud instead of your local machine.

Second, since you have already published this app before (step #3), you need to republish your application.

Use the --force option with the publish command to overwrite the previous deployment: 

Once again, the appc cloud publish command returns the URL for your application. Open a web browser and enter the application's URL to visit the app in the cloud.

That's it! You made it! Enjoy!

  • No labels