An app's API defines the kinds of calls or requests that can be made by the app's frontend, how to make them, how they are handled by the backend, the data formats that should be used, the conventions to follow, etc.
Imagine allows you to represent your app's backend API handling using the following structure and syntax:
As an example of a API, let's take the music app, Musica, that has the concepts of API handling for the api-name musician-profile.
Representation in Imagine syntax
The Musica API handling would be represented in Imagine's syntax as follows:
Imagine's API settings allow you choose whether you want your API to be represented in RestAPI or GraphQL format.
We will describe the various elements in this module in detail below.
Imagine's API module allows you to create API endpoints that can manipulate data models in your app.
Note: We do not current support making API calls in the app's frontend. We will allow this capability in future releases, when we support frontend frameworks like React.
The various elements of Imagine's API module are as follows:
In our syntax, API is followed by a unique user-selected
<api-name> (or /
<api-name> - the forward slash
/ is optional) for that API endpoint. Please see this for rules on selecting a
In the example below, musician-profile is an
<actions> allow you to define how you want to manipulate a data model.
The Imagine compiler currently supports the following
- Create - Creates a new object instance in a data model. The payload consists of data for fields of the data model.
- Read - Reads one instances of a data model from the storage. The payload consists of the unique identifier for the object
- Update - Updates one or more fields for an instance of a data model. The payload consists of values of the fields that should be updated.
- Delete - Deletes an instance of a data model. The payload consists of the unique identifier for the object
- CRUD - Implements all CRUD (Create, Read, Update, Delete) actions on a data model.
- ReadMany - Reads many instances of a data model from the storage after filtering by certain criterion. By default, the API would return all instances. (The API caller can also use filter to provide a way to specify which objects to read)
In addition to the common API
<actions> listed above, a typical app has a number of custom APIs, specific to the app's use case, that implement different functionalities within the app. While you would write the code for any custom APIs yourself, you can generate an custom API code template using Imagine by specifying custom as your API
<action>. You can read mode about the specific syntax required for this in the custom API code module.
In the example below, see a CRUD API config that implements all of the CRUD actions on a particular
<permissions> allow you to select which of the
<permissions> defined in the Authorization domain are needed to be able to access this particular API handler.
Note: If no permissions are specified in the API module, the API handler is accessible to all API callers in the app.
In the example below, see a /publish_album API that
<model> allow you to select the model you want to manipulate with this particular API handler.
In the example below, the /publish_album API manipulates the Musician model
<data> specifies the data that the API handler should expect or return.
Note: A special keyword ALL can be used to indicate all fields of the Model to be included in the data.
In the example below, the /musician-profile API only returns the data relevant to be shown in a profile page. Other data which are not needed for the profile page is not returned.
<filter> lists the various data fields on which an API can be filtered, and is only applicable for Read and ReadMany
Note: A special keyword ALL can be used to indicate all fields of the Model to be included in the filter list.
In the example below, the API would allow filtering based on
If you want to create a custom API handler with
<actions> outside the supported CRUD actions, we provide a simple scaffolding for custom APIs.
While the code for the custom logic for a custom API to be filled in by the app developer, we help generate the code for permissions checking for the API.
A custom API is created by specifying custom as the actions within the API module.
Note: If you are defining the
<action> as custom, the API module, will not support
<data> parameters. If you use any of these parameters, with a custom
<action> chosen, the compiler will return an error, as you will need to write custom specifications for a custom API.
In the example below, [Config for a custom API /make_payment that requires the caller to have the permission
[The generated code will do the permissions checking but will require the app developer to fill in the code required for executing the payment.