Welcome to Arrow Project

You should replace the contents of this file with something meaningful. This is a placeholder file to help you get started. Got it?

Overview

This is a skeleton API Builder API project. The project is organized into several different directories and key files. This project is built to run either as a standalone Node server during development and also it is configured to run on the Appcelerator Cloud Services (ACS) platform.

Get Started

First, you should make sure you're environment is setup and ready to go. To get started, let's make sure you can run the project, view the documentation and test the sample generated API.

$ appc run

If everything goes well, you should see output similar to the following:

$ appc run
Appcelerator Command-Line Interface, version 0.1.48
Copyright (c) 2014-2015, Appcelerator, Inc.  All Rights Reserved.

Installing dependencies... server
[INFO]  Installing dependencies...
[INFO]  Dependencies installed.
[INFO]  APIKey is: G2UVPfGY+9AyWhih0AUgKFD9CSdRIm4W
[INFO]  Test your APIs at http://0.0.0.0:8080/arrow. This will only be available on your dev environment
[INFO]  server started on port 8080
[INFO]  API documentation generated at http://0.0.0.0:8080/arrow/doc

NOTE: You may need to login to the Appcelerator platform using your Appcelerator credentials the first time you run or if you have not logged in before.

After starting the server, you should be able to browse to the main API documentation page by navigating to http://127.0.0.1:8080/arrow/doc.

If the page renders with the test API, you're ready to get started building your APIs!

Project Structure

The project has the following main folders:

• conf - your configuration files will go here
• apis - your APIs will go here
• models - your models will go here
• specs - your tests will go here
• docs - your API docs will go here
• logs - your server logs will be generated to this directory by default

In your root project folder, you will have the main server file app.js. This file generally should not need to be edited but you can edit it if you want to further customize your server.

Configuration

The main configuration file is located in conf/default.js. This file is the base configuration file. You can have environment specific configuration by including a file with the name of the environment in the conf directory such as local.js or production.js. Values configured in this file will be merged into the default.js file. This allows you to create a base set of configuration values and then override them depending on your environment. By default, the local.js file will be ignored by git during checkin. If you want to change this behavior to allow you to check in this file, change the entry in conf/.gitignore.

Base Configuration

The following are configuration settings used by API Builder that can be customized:

Name	Description	Default value
logs	the folder to place your logs. if missing, will not log to disk.	./logs
quiet	if true, will suppress logging to console	false
logLevel	log level of main logger	debug
apikey	API key for accessing the server	n/a
admin	hash for controlling admin access	n/a
session	hash for controlling session	n/a

The admin setting has the following properties:

Name	Description	Default value
enabled	if true, will enable the admin functionality	true
prefix	the URI path prefix	/arrow

The session setting has the following properties:

Name	Description	Default value
encryptionAlgorithm	the encryption algorithm to use	aes256
encryptionKey	the encryption key (should be unique and private)	n/a
signatureAlgorithm	the signature algorithm to use	sha512-drop256
signatureKey	the signature key (should be unique and private)	n/a
secret	should be a large unguessable string	n/a
duration	how long the session will stay valid in ms	86400000
activeDuration	if expiresIn < activeDuration, the session will be extended by activeDuration ms	300000

APIs

APIs must be placed in the apis folder. You can create subfolders under the apis folder to organize your APIs.

An API is defined using the following example:

var Arrow = require('arrow');

var TestAPI = Arrow.API.extend({
    group: 'test',
    path: '/test/:id',
    method: 'GET',
    description: 'this is an api that show how you can implement an API',
    model: 'user',
    parameters: {
        id: {description:'the user id'}
    },
    action: function (req, resp) {
        // invoke the model find method passing the id parameter
        // stream the result back as response
        resp.stream(req.model.find, req.params.id);
    }
});

module.exports = TestAPI;

An API has the following properties:

Name	Description	Default value
name	name of the API. use the same name to group API endpoints together	n/a
path	the path route to the API	n/a
method	the HTTP verb for accessing the API	GET
description	the description used in documentation to explain this API	n/a
model	optional name of the Model that this API returns	n/a
parameters	optional hash of incoming properties (path or query) used by this API	n/a
action	function that will be called to implement the API	n/a

The API will automatically be loaded and created when you start the server.

Documentation

APIs which are grouped together have each API endpoint documented at the API definition. You can provide extended overview documentation for all APIs which share the same name by creating a file with the name of the API in the docs folder, such as test.md. The contents of this file must be authored Markdown (powered by some special extensions). You can view an example of how to author by viewing the generated file named test.md in the docs folder. The contents of the file will be included as part of the definition of the API.

Models

Models must be placed in the models folder. You can create subfolders under the models folder to organize your Models.

A Model is defined using the following example:

var Arrow = require('arrow');

var User = Arrow.Model.extend('user',{
    fields: {
        first_name: { type: String },
        last_name: { type: String },
        email: { type: String }
    },
    connector: 'memory'
});

module.exports = User;

Models are automatically loaded by the server and automatically bound to a route with the appropriate CRUD methods.

You can automatically get a model programatically:

var user = Arrow.getModel('user');

The result will always be the Model definition, not an instance.