The Structure of an API Extension Application

API Extension applications contain JavaScript files that run custom functions before or after a specific action occurs in Kibo. The available actions are organized into domains that relate to the component they interact with. The following diagram provides a visual demonstration of this structure. Note that while most actions run only one function, some actions can run multiple functions. 

Chart showing the hierarchy of a domain, its actions, and their function

API Extension Project Files

The project files in which you develop API Extension applications have the structure shown in the following image. You can use the Yeoman Generator to automatically scaffold these files.


Example of a root folder showing the project files

assetsThis folder contains the subfolders where you code your custom functions and design your tests. When you run Grunt, all the files in the assets folder are uploaded to your application in Dev Center.
Gruntfile.jsThis file defines Grunt task configurations and loads Grunt plugins. Grunt tasks automate the repetitive aspects of API Extensions development and are invoked through the command line. You can add custom Grunt tasks to this file if you wish. The default Grunt commands include:
  • grunt: Runs grunt build. In addition, asks for your developer account password in order to upload your assets to Dev Center. If your tests fail, you can append --force to the command to force the upload.
  • grunt build: Lints your code, bundles your dependencies, runs tests, and creates the dist folder and functions.json file, but does not upload the assets to Dev Center (making this command useful for development). If your tests fail, you can append --force to the command to force the build.
  • grunt test: Runs the tests associated with your action files (you can edit these tests in the assets/test directory).
  • grunt reset: Deletes all assets from your project folder and from Dev Center.
  • grunt w: Enables a watch that runs grunt every time you save a change to a project file. Unlike in theme development, where you can refresh a browser page to test most changes, setting a watch is normally not useful for API Extensions development, where you are more likely to test your changes across larger intervals. An exception when you might want to set a watch is if you are using API Extensions to alter view data for the theme.
mozu-config.jsonThis file stores authentication credentials for the application, sync app, and your Dev Center account.
package.jsonThis file stores npm module metadata (like the package name and version number) and includes a list of dependencies for the application (for example, Grunt dependencies, development tools, and any external Node.js libraries that the application leverages).

assets folder

distThis folder contains built and optimized assets that result from the Grunt build task.
srcThis folder contains a list of domain folders. Each domain folder contains JavaScript files that pertain to specific actions. The Grunt build task creates optimized versions of the files in the src folder and places them in the dist folder.
testThis folder contains JavaScript files where you can design simulations and tests for your application. Each file corresponds to a source code file in the src/domains folder.
functions.jsonThis file specifies how the custom functions in your JavaScript files (within the src folder) map to actions for your application to implement.

src folder

domainsThis folder contains the JavaScript files where you code your custom functions. The files are named for the action they bind to and are organized by the domain to which the action pertains. For example, the embedded.platform.applications.install.js file, in the platform.applicationsdomain folder, is where you code the custom function that binds to the action that occurs when the application is installed to a sandbox.
manifest.js filesThese files define the relationship between custom functions and the actions they bind to. The build task autogenerates these files based on the settings you specify in the Yeoman scaffolding tool, and then leverages the manifest files to generate the functions.json file.

The Structure of the Action Files

The action files are the Javascript files in which you code the custom functionality that you want to bind to actions. The naming and structure of these files follows the REST resource hierarchy.

Filename Syntax


TypeIdentifies the type of action.
DomainIdentifies the domain of the action, which specifies what part of the API hierarchy the action interacts with. For example, commerce.carts or commerce.customer.
ActionIdentifies the HTTP or action that runs the custom function. For example, updateItem.

Specifies whether the custom function runs before or after the HTTP or Kibo action occurs. For example, for an HTTP action, before runs the function when the HTTP request occurs in Kibo but before Kibo executes the request, and after runs the function after Kibo executes the request and is ready to send the HTTP response. Not every action includes this element.



This embedded action executes the custom functions associated with it after a price for an order is set.

To see the full list of actions available in API Extensions, refer to the reference documentation.