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?
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.
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 runAppcelerator Command-Line Interface, version 0.1.48Copyright 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!
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.
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
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
The following are configuration settings used by API Builder that can be customized:
|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|
admin setting has the following properties:
|enabled||if true, will enable the admin functionality||true|
|prefix||the URI path prefix||/arrow|
session setting has the following properties:
|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 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 = ;var TestAPI = ArrowAPI;moduleexports = TestAPI;
An API has the following properties:
|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.
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 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 = ;var User = ArrowModel;moduleexports = 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;
The result will always be the Model definition, not an instance.