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.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Made minor grammar and spelling changes

...

Note

The content on 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.

...

Place all API definition files in the project's apis folder. You can only declare one endpoint definition per file. An API definition file is a JavaScript file, which:

  1. Loads the arrow module.
  2. Calls the module's API.extend() method, passing in an object defining the API endpoint and logic.
  3. Exports the defined endpoint using the module.exports variable.

Set the following keys in the object passed to the API.extend() method to define the API endpoint:

NameRequiredDescription
grouptrueThe logical name for grouping API endpoints.
pathtrueRequest path (e.g., ‘/api/user/:id’). Prefix paramaters with a colon (:).
methodtrueHTTP verb (‘GET’, ‘POST’, ‘PUT’, or ‘DELETE’).
descriptiontrueDescription of the endpoint, which is used in the generation of the API endpoint documentation.
modeltrueThe model to use for the response. An API endpoint can only specify one model, but model’s models can be composed of other models and fields.
actiontrueFunction that is called to execute the API endpoint’s logic. The function is passed a request object, response object, and next() method. Use this function to make programmatic calls to your model’s methods for reading or writing data and to do other things related to the custom business logic of your API endpoint including making calls to other node modules that your API endpoint requires. You should always make sure that your action function calls the next function regardless if the result is a success or an error. 
documentedfalseSince Release 5.0.0. Determines whether to generate API documentation (true) or not (false). Default is true.
responsefalseThe response model for the API. This should only be used if your request and response models are different.
pluralfalseA string used as the property name when your API endpoint returns an array. By default, the plural value is the plural of the model name. For example, if your model is named car, the default plural would be cars.
singularfalseA string used as the property name when your API endpoint returns a single record. By default, the singular value is the name of the model.
beforefalseOne or more API Builder Blocks to be executed before the request. Blocks are referenced by their name property. If you want to execute multiple blocks, you should specify them as an array of block names. If multiple blocks are specified, they are executed in the order specified.
afterfalseOne or more API Builder Blocks to be executed after the request. Blocks are referenced by their name property. If you want to execute multiple blocks, you should specify them as an array of block names. If multiple blocks are specified, they are executed in the order specified.
parametersfalse

Input parameters required to execute the API endpoint. This is an object of key-value pairs, where the key is the name of the parameter and the value is an object with the following properties:

  • optional (Boolean): Determines if the parameter is optional (true) or required (false).
  • type (String): the type of input parameter: ‘path’, ‘query’, or 'body'.
  • description (String): used for generating API documentation.

...

The following API definition file creates an endpoint that can be accesses accessed by a client using GET <HOST_ADDRESS>/api/test/:id. Before the request is initiated by the server, the formatRequestBlock is executed, then the server performs the request (executes the action logic). The action logic tries to find the user model with the specified ID. After the logic executes, the cachingBlock and analyticsBlocks are executed.

...