The platform allows you to create custom API methods as a part of your module and then use them in a web API or scripts in widgets, pages, and business processes. For example, you can create methods for starting a business process, complex data fetching, or set up methods for interaction with an internal or external system. You can create general-purpose methods and use them in different places repeatedly.
To create or edit a method:
- Go to Administration > Modules.
- Hover the mouse over the module and click the gear icon.
- Go to the API Methods tab.
- Click Edit. The method editor will open.
- Click the +Add button. In the window that opens, enter the required information.
- Name*. Enter the method name.
- Address*.Select HTTP request method: GET or POST. Specify at what address to access the method.
- Function*. Create a function to execute when getting a request.
- Authorization*. Select an authentication type to use when getting a request.
- Internal authentication. When this option is checked, the method can only be called within the module using the Namespace.api.method_name command, for example, in other methods, widgets, business processes activities, event handlers. Read more below. The user on whose behalf the script is performed must be logged in ELMA365.
- External authentication. When this option is selected, the method will be available from the external system by a token.
- Asynchronous start. This option allows you to continue your work without waiting for method execution to finish.
- Description. Write a detailed description of the method here.
- Go to the Scripts tab and write the method source code. Use the TypeScript programming language. If you'd like to know more about the basic principles of scrip-writing in ELMA365, please visit TypeScript SDK Help Center.
- Save and publish the method.
Access to the Global constant
You can use the Global constant in API methods to access variables inside workspaces and global parameters. But, using such a constant prevents the module downloading. It means that enabling access to the Global constant in API methods limits the module export.
To enable the access to the Global constant:
- In the method editor, go to the Scripts tab;
- In the top menu, click Settings;
- In the window that opens, select the Global option.
Call an API method from a script
After creating an API method in a module, you can call it in any script of the same module. To do this, use an api property in the Namespace global variable:
let response = await Namespace.api.some_method.call({
method: "POST",
headers: {
"X-My-CutomHeader": "Some header data"
},
query: {
"skip": "0",
"take": "10"
}, body: "Any body here"
});
The FetchRequest type is sent to this method and is used in the fetch method.
When this method is called, a web call to the API method is made through the standard HTTP protocol. Therefore, the response from the method comes in the form of a standard FetchResponse object.
To configure modules with webhooks, you can get the API method address using the Namespace.api.some_method.getUrl() command. It will return a string with the full address of this method for further calling. This method is useful when working with a third-party service, when it requires you to specify a return address for a call.
Found a typo? Highlight the text, press ctrl + enter and notify us