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


This guide describes how to convert your API Runtime Services application using the MVC framework to work in the API Builder framework.

For details about API Builder, see API Builder Tools.

Create an API Builder project

Before starting, first create an API Builder project by executing the command below in your workspace directory: 


If you have any special settings or dependencies in your API Runtime Services project's package.json file, add them to the same file in your new API Builder project. Do not overwrite any existing keys.

Express app instance

To access the Express instance in an API Builder project, use the app property of the API Builder instance. For the API and Route components, an API Builder instance is passed to the request and response objects as the server property.

Express version


API Runtime Services used Express 3.x, while  API Builder uses Express 4.x. For details about migrating to Express 4, see http://expressjs.com/guide/migrating-4.html.



Socket.io instance

An API Builder application does not include socket.io by default.  To include socket.io in an  API Builder application:

  1. In the package.json file, add  socket.io as a dependency.
  2. In the app.js, in the started event listener, load the socket.io module and pass it the server instance ( API Builder instance's server property), then make API calls to the socket.io instance.  If you assign the socket.io instance to a property of the  API Builder instance, you can access the socket.io instance with that property wherever an  API Builder instance is passed to a method.
  3. Any client-side code, such as the view templates, will need to include the socket.io.js client script.  Note that when the client connects to the socket.io server ( API Builder application), you will need to update the URL when switching between testing the project locally or when it's published to API Runtime Services.


The following example creates a basic chat application. 

Add socket.io as a dependency to the API Builder project.


Loads the socket.io module and creates an instance.


Then, add the socket.io client code to your views or other client-side code.


Note you need to implement an API Builder Route to render the HTML.



If you add any logic to the start() or stop() methods in the app.js file, you can add the same logic in the API Builder instance's event listeners for the starting and stopping events, respectively.


The API Runtime Services project logs in and out of an Mobile Backend Services (MBS) account when the application starts and stops.  The same method calls can be added to the event listeners in an API Builder application.




All routes declared in the config.json file of your API Runtime Services application may be declared as a:

  •  API Builder Route located in the web/routes folder of the API Builder project if the route renders UI. For details, see the example below and API Builder Web.
  • API Builder Model if the route is a simple data object stored in the cloud that you want to have standardized HTTP endpoints. For details, see Models.
  • API Builder API if the route performs more complex operations and you want to have a custom HTTP endpoint. For details, see APIs - Legacy.


The config.json file defines a route that when someone accesses SERVER_ADDRESS/foobar, the API Runtime Services application executes the bar() method in the controllers/foo.js file.


To use the same route in API Builder, create a CommonJS module, which loads the arrow module, then call the module's Router.extend() method to declare the route.  Pass a dictionary to the extend() method with the following keys defined (all keys are required):

nameThe name of your route.
pathThe endpoint/path for your route.
methodHTTP verb ('DELETE', 'GET', 'POST' or 'PUT').
descriptionA description for your route. This is used for documentation purposes.
actionFunction that allows you to interact with API Builder APIs and Models and send data to your template engine.

Finally, expose the route using the modules.exports variable.



All filters declared in the config.json file of your API Runtime Services application may be declared as an Arrow Block module that can be assigned to the before property in the definition file of an  API Builder Model or API.


For all websockets declared in the config.json file of your API Runtime Services application, you will need to add an event listener to the socket once a connection is established, which requires socket.io to be added to the project. For details, see the socket.io instance section above.


The config.json file defines a websocket that whenever a newChatMsg is received, the API Runtime Services application executes the receiveMessage() method in the websockets/chatroom.js file.


To use the same websocket in API Builder, first add socket.io as described in the socket.io instance section, then add a newChatMsg event listener for the socket in the connection event listener.


Controllers directory

All logic declared in the API Runtime Services controllers should be moved to the API Builder Route module in the web/routes folder of the API Builder project or API Builder API module. For details, see the config.json section above.

Filters directory

All logic declared in the API Runtime Services filters should be moved to the API Builder Block module.

Websockets directory

All logic declared in API Runtime Services websockets will need to be declared with the socket event listener, which requires socket.io to be added to the project. For details, see the config.json section above.

Public directory

Copy all files in the public folder of your API Runtime Services application to the web/public folder in the new API Builder project.

Views directory

Copy all files in the views folder of your API Runtime Services application to the web/views folder in the new API Builder project.


API Builder also supports other template engines including Handlebars, Markdown and ReactJS.

Run the API Builder project

After you have made your changes, to test the project, run or publish the API Builder project.

To run the API Builder project locally, execute the following command from the project's directory:

Publish the API Builder project

To publish the API Builder project to the cloud, execute the following command from the project's directory:

This will produce a new URL, different from that of your existing API Runtime Services project. For migrating ACS data (legacy) to Mobile Backend Services, we will take care of migrating your ACS data to the platform in time and notify you when we do. Your ACS keys and endpoints will not change, so no changes are needed to (Titanium) client applications. During the migration, we expect 1-2 hours of downtime. After the migration, you can manage your ACS data via the platform dashboard.