This chapter covers the basics for creating API endpoints. API endpoints are automatically generated for all models, but there may be cases where you will want to create your own custom API.
An API provides a way for a client to access your application, such as
GET <SERVER_ADDRESS>/api/users/query, execute custom logic and internally access the application's models and APIs, then return data back to the client application.
To programmatically create an API, see the API Builder.API reference.
Place all API definition files in the project's
- Loads the
- Calls the module's
API.extend()method, passing in an object defining the API endpoint and logic.
- Exports the defined endpoint using the
Set the following keys in the object passed to the
API.extend() method to define the API endpoint:
|true||The logical name for grouping API endpoints.|
|true||Request path (for example, |
|true||HTTP verb (|
|true||Description of the endpoint, which is used in the generation of the API endpoint documentation.|
|true||The model to use for the response. An API endpoint can only specify one model, but models can be composed of other models and fields.|
|true||The function that is called to execute the API endpoint’s logic. The function is passed a |
|false||Since Release 5.0.0. Determines whether to generate API documentation (true) or not (false). The default setting is true.|
|false||The response model for the API. This should only be used if your request and response models are different.|
|false||A 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.|
|false||A 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.|
|false||One or more API Builder Blocks to be executed before the request. Blocks are referenced by their |
|false||One or more API Builder Blocks to be executed after the request. Blocks are referenced by their |
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:
The following API definition file creates an endpoint that can be 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
analyticsBlocks are executed.
Invoke API endpoints in API Builder
Any callback in the application that is passed the
request object can access the endpoints programmatically.
To invoke an API endpoint:
- Retrieve an instance to API Builder using the
- Retrieve the API instance using API Builder's
getAPI('endpoint', 'verb')method by passing it the endpoint without the server host or address as the first parameter and the HTTP verb as the second parameter.
- Invoke the
execute(params, callback)method on the API instance by passing it a dictionary of parameters as the first parameter and a callback function as the second parameter. The callback function is passed an
The Route below is invoking the
GET <SERVER_ADDRESS>/api/car method programmatically.