Can I call Kuroco's API using custom function?
There are two ways to call Kuroco's API using custom function.
- Use the
api_internalplugin - Use the
api_methodplugin
Each of these ways is explained below.
Use the api_internal plugin
By using the api_internal plugin, you can call any endpoint configured on the API screen and get the execution results.
Examples of the usage is shown below.
Example 1. GET method (no authentication)
{* query parameter *}
{assign_array var='queries' values=''}
{assign var='queries.filter' value='ext_col_01 = "1"'}
{api_internal
var='response'
status_var='status'
endpoint='/rcms-api/1/topics'
method='GET'
queries=$queries}
Calls the target API via HTTP request and assigns the response to the variable specified as var.
The variable specified as status_var is assigned the success or failure of the request.
Returns 1 in case of success, or 0 in case of failure due to network errors or other factors.
The execution of the above sample code corresponds to the following JavaScript code. The request is sent with the filter condition of ext_col_01 = "1" specified in the query parameter of the endpoint /rcms-api/1/topics.
let queries = {};
queries.filter = 'ext_col_01 = "1"';
fetch(
'https://your-site-key.g.kuroco.app/rcms-api/1/topics?' + (new URLSearchParams(queries)).toString(),
// => https://your-site-key.g.kuroco.app/rcms-api/1/topics?filter=ext_col_01+%3D+%221%22
{
method: 'GET',
}
);
Refer to the following document for details on how to use filters.
- Tutorial -> Implementing a search function
- References -> Using the filter query function
Example 2. POST method (with authentication)
{* Request Body *}
{assign_array var='body' values=''}
{assign var='body.subject' value='Title'}
{assign var='body.ext_col_01' value='2'}
{api_internal
var='response'
status_var='status'
endpoint='/rcms-api/2/topics/insert'
method='POST'
queries=$body
member_id=$smarty.session.member_id}
Passing the member_id parameter allows the request to be executed with the specified member ID authenticated.
The member_id parameter can be specified only when the authentication method of the target API is set to "dynamic access token". If you wish to use it, it is recommended to create a separate API for internal processing.
For information on dynamic access tokens, see API Security -> Dynamic Access Tokens.
The execution of the above sample code corresponds to the following JavaScript code.
let body = {};
body.subject = 'Title';
body.ext_col_01 = '2';
fetch(
'https://your-site-key.g.kuroco.app/rcms-api/2/topics/insert',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
// Generate an access token based on the member_id specified and grant it automatically.
'X-RCMS-API-ACCESS-TOKEN': '********',
},
body: JSON.stringify(body),
}
);
Example 3. GET method (direct execution on server)
{assign_array var='queries' values=''}
{assign var='queries.filter' value='ext_col_01 = "1"'}
{api_internal
var='response'
status_var='status'
endpoint='/rcms-api/1/topics'
method='GET'
queries=$queries
direct=1}
The process in 'Example 1' and 'Example 2' calls the target endpoint via HTTP request. However, depending on network conditions, the following problems may occur.
- Takes time to get results
- Failure to retrieve results
As a countermeasure, you can specify direct=1 as a parameter to execute the endpoint processing directly on the server without going through the HTTP request.
This has the advantage of stable results, but response caching does not work, so you would have to consider the cost of using this approach.
You can specify direct=1 as a parameter only when the HTTP method of the target endpoint is GET. Furthermore, member_id cannot be specified.
Example 4. GET method (request inheriting session state)
{* query parameter *}
{assign_session key='my_session_name' value=true}
{assign_array var='queries' values=''}
{assign var='queries.filter' value='ext_col_01 = "1"'}
{api_internal
var='response'
status_var='status'
endpoint='/rcms-api/1/topics'
method='GET'
queries=$queries
direct=1
use_current_session=1}
Under normal circumstances, separate sessions are created for the caller and the destination of the api_internal plugin.
However, if direct=1 and use_current_session=1 are specified at the same time, the target endpoint can be processed while inheriting the caller's session.
Therefore, it is useful when you want to execute directly with the login state inherited, or when you use the assign_session plugin to manage your own session variables.
We can confirm that the session state is the same as that of the caller by defining the following in Smarty code in the pre-processing or post-processing of an endpoint.
{* $my_session_value is assigned the session set by the caller *}
{assign_session var='my_session_value' key='my_session_name'}
{* The caller's login status is inherited *}
{assign var='member_id' value=$smarty.session.member_id}
Use the api_method plugin
The api_method plugin allows you to call API functions directly without creating endpoints.
As with calling the api_internal plugin with the direct=1 parameter, processing is performed on the server without going through an HTTP request. The API call function automatically inherits the same session state as the caller.
The api_method can only be called if the HTTP method of the target function is GET. If you need to execute a POST method, create the endpoint in advance and call it via the api_internal plugin.
api_method plugin usage example
{* Endpoint Configuration Parameters *}
{assign_array var='method_params' values=''}
{assign_array var='method_params.topics_group_id' values='1'}
{assign var='method_params.cnt' value=10}
{* query parameter *}
{assign_array var='request_params' values=''}
{assign var='request_params.filter' value='ext_col_01 = "1"'}
{api_method
var='topics'
model='Topics'
method='list'
version='1'
method_params=$method_params
request_params=$request_params}
The execution result is assigned to the variable specified as var.
The data assigned to the $topics variable in the above example will be the same as the result of executing a request on the API screen with the following endpoint
Endpoint Configuration
Request
fetch(
"https://your-site-key.g.kuroco.app/rcms-api/{api_id}/topics?filter=" + encodeURIComponent('ext_col_01 = "1"'),
{
"method": "GET",
}
);
Use of api_internal plugin and api_method plugin
The api_internal plugin must call an existing endpoint, while the api_method plugin does not.
Therefore, we recommend using api_internal if you wish to reuse existing endpoints and api_method if you do not need to use endpoints.
Related Documents
Support
If you have any other questions, please contact us or check out Our Slack Community.