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

Icon

The content on this page is for the beta release of API Builder 1.10.0. You may find some information is either missing, incomplete or in general draft state.

Introduction

This guide walks through the steps to create, run, and deploy an application while allowing you to get familiar with some of the tools involved.

An API Builder application allows you to build and deploy API endpoints to the cloud that can be consumed by a client application.

Setup

To create an application, you need the Appcelerator CLI. If you are using Appcelerator Studio 4.0 or greater, the Appcelerator CLI is automatically installed for you. To manually install the CLI, install a modern version of Node.js, and then install Appcelerator:

  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 log in, select an organization to log into, and asked you will be developing Titanium apps. If this is your first time using Appcelerator Studio, the CLI will ask to send an authorization token to your e-mail account or a text to your mobile phone. Enter the authorization token once you receive it to complete the registration process.

Create a project

To create a new project, go to your workspace directory and execute the following command:

The CLI will prompt you for a project name. After entering a name for your project, the CLI will create a new skeleton API Builder project for you.

Run the project

To run the project locally, from the project directory, execute the following command:

The CLI will download and install any dependencies for the project and then start the application. The application will launch a server instance that you can access from a web browser or another client. As the app is launching, you will see the various services it is starting and the localhost URLs for this app. Typically, the URL should be  http://localhost:8080/. Open a browser and navigate to the application's URL. If all went well, you should see the Arrow logo.

Access the Admin site

By default, when you create a new project, the Admin Console is enabled and is available using the arrow path that should be this URL:  http://localhost:8080/api-create-ui

Navigate to the Admin Console in your web browser.

Upon reviewing the left navigation, you can navigate to the following items:

 

SummaryYour app's admin home page.
ConnectorsLists and filters installed connector.
ModelsInterface to help you build models. A model represents data stored from another source.
API Doc & TestAuto-generated documentation about your API endpoints. Provides help for the client application to access your application.
ConfigurationsLists configuration files that you can modify and save within a browser.
LogsLists of access logs, clients trying to access your application.
View DocumentationLinks to Appcelerator's documentation site for API Builder's guide.
Sidebar toggleToggles the width of the sidebar.

You can disable the Admin Console by changing the configuration settings in the conf/default.js file. For now, let's explore some of the features of the Admin Console.

Create a new model

Let's create a new model using the Admin Console. In the Admin Console,

  1. Click the  Models button. 
  2. Click the + Model button on the right side.
  3. In theNew Model step,
    1. Enter "simpleuser" in the Model name field (required). The name must be unique for all of the application's models.
    2. Select a Connector from the drop-down list (required). Connectors are used to persist data to the model.
    3. Add a description.
    4. Click Next to move onto the fields step
  4. In the Create Model Fields step,

    1. Click the + Field button.
    2. Enter "first_name" in the Field name field (required).
       
    3. Set Type to String.
    4. Leave Default value empty.
    5. Add a description.
    6. Check the boxes for Read-only or Required as necessary.
    7. Click the Add field to model button.
    8. Repeat step 4 as necessary to add the "last_name" and "email" fields to this model. After you add the fields, you can configure them by changing properties or adding validation or return logic.
  5. In the API endpoint page,

    1. Make sure the CreateRetrieve, and Update methods are checked. Since the Delete method is not checked, the DELETE api/simpleuser endpoint will not be generated but all the other default endpoints for this model will be.
    2. Click Save to commit your new model to the app.

If you look in your project's models folder, notice you have a new file called simpleuser.js. This file was just created by the Admin Console. Instead of creating a model using the Admin Console, you can define one using JavaScript files in the project's models directory.

Access model data

Now that you have created the simpleuser model, let's try to retrieve the model data from the application. In the Admin Console:

  1. Click the  API Docs & Test tab. This page lists all the API endpoints that you application exposes.
  2. Click anywhere on the row of any one of the API endpoints that you recently created. The Admin Console presents all the API endpoints that can be used to access a particular model.
  3. Expand one of the GET methods in your endpoint. The code sample for curl should be visible. If it's not, click it now.
  4. Copy a curl command and run it in a terminal. Note the message returned by this command.
  5. Now let's take a look at the logs to see if the command registered with the app. Click the  Logs tab. You should see all recent requests made to/from your app here.
  6. If the list of events in the logs is rather long, you can filter and/or search for particular events. In the Time drop-down (by default, it says All Time because the log is reporting back all events), select Past 10 Minutes. If the list is still long, you can filter by and Status as well. Once you found your curl call, click it to see the full report of that event.
     

Test other API endpoints

With a new project (by default), you can navigate to the app's API auto-generated documentation and it's examples pages by pointing a browser to http://localhost:8080/apidoc and  http://localhost:8080/example respectively.

The example URL shows a simple example of an Arrow Web interface. An Arrow Web interface creates an API endpoint with access to a render engine and your Model data that displays HTML content.

After locally testing the application, let's try it out in the cloud. To stop the server, hit command/control + C in the terminal where you launched the app.

Deploy the project

To deploy the project to the cloud, from the project directory, execute the following command:

It will take a few minutes for your application to be deployed to Arrow Cloud. After the command completes, the URL to your application will be displayed in the console.

Let's quickly test the published application. In your browser, navigate to your published cloud application. You should see the Arrow Logo.

Next, go to the project's documentation. Add the /apidoc path to the end of the URL to retrieve the application documentation and endpoints. Retrieve the curl example of the query endpoint and execute it in the terminal. The command should return the same results when you tested the project locally.

View analytics

To view analytics about your project, go to the Appcelerator Dashboard.

  1. In a browser, navigate to https://platform.appcelerator.com.
  2. Click the Apps menu and select All Projects. You will be presented with a list of all your applications.
  3. Locate your new application. There will be two entry types for your application: Arrow and ArrowDB. The application is the published application that you interact with. The ArrowDB datasource is essentially cloud storage where all your model data (at least for this example) is stored. The simpleuser model data you entered previously is stored here.
  4. Click the type of your application. You will be presented with an analytics overview of your application with data about API calls and the server(s) your application is running on.
  5. Click the tab in the left navigation to view more detailed information about your application.

Next steps

Review the API Builder Project page to learn more about API Builder projects, then review the other subtopics in the API Builder page to learn how to build the components for your project.