Pre-processing

Pre-processing is a user-defined custom function that is called before executing the main process of API endpoints. You can set pre-processing to the configured endpoints.

tip

The processing logic implemented in the pre-processing is not reflected in the API information (Swagger UI) page or the openapi.json file, so there may be differences between the information displayed on the screen and the actual specifications. For this reason, it is recommended that the specifications of the customised parts are described in the endpoint description instead.

Steps to set up pre-processing in endpoints

Pre-processing can be set up in the following steps.

1. Write the pre-processing logic in the custom function
2. Add the custom function in the pre-processing settings of the endpoint

The detailed information of the above steps are as follows:

Write the program in the custom function

Access the custom function editor page and create a custom function for the pre-processing logic.

To avoid confusion with custom functions created for other purposes, it is recommended to set it up according to the following rules.

• Create a category to group the pre-processing custom functions together
• Set the title of the custom function to be the same as the path name of the endpoint, so that it is easier to identify and associate them together.

Associate the custom function with the endpoint settings

1. Access API list page

Select the API on the side menu and access API list page.

2. Select the endpoint

Select the endpoint you want to implement and click the [Pre-processing] button.

3. Add a pre-process and select the custom function

Select the category that the custom function is grouped under then select the custom function by its title under the Contents field to associate the custom function to the pre-processing of the endpoint.

caution

The endpoint may not work as expected if the incorrect custom function is selected in the endpoint's pre-processing settings.

Variables of pre-processing

Variables used in pre-processing have reserved words with specific meanings. These variables may be used to customize the behaviour of the endpoint.

Variable	Usage
$meta	Data reference (read only)
$url	Data reference (read only)
$body	Data reference (read only)
$errors	Custom error handling (write action)
$request	Modify API request body (write action)

Variables for reference

The following variables are reference variables that are always assigned by default when pre-processing is executed.
They are used to determine the endpoint information and the request value passed.

Variable name	Description
$meta	Meta data of the endpoint
$url	URL component
$body	Request body

$meta

This variable contains the meta data of the associated endpoint.

Variable	Type	Description
$meta	object	All meta data of the endpoint

This variable contains the following data.

Key	Type	Initial value	Description
$meta.content_type	string		Content-type
$meta.mime	object		MIME type and MIME sub-type
$meta.mime.type	string		MIME type
$meta.mime.subtype	string		MIME sub-type
$meta.output_format	string	"json"	_output_format specified in query parameter
$meta.lang	string	Determined based on the following priorities: [Browser language > Main language settings]	_lang specified in query parameter
$meta.charset	string	"utf8"	_charset specified in query parameter
$meta.http_code	string	null
$meta.api_header	object		API settings
$meta.post_json	string	GET: null POST: "{}"	JSON body in text format

$url

This variable contains the component of the URL specified by the client.

Variable name	Type	Description
$url	object	Endpoint path and query parameter data

This variable contains the following data.
Among the following, $url.query contains the same value as $smarty.get.

Key	Type	Description
$url.path	string	Path of the endpoint
$url.query	object	Query parameter

For example, for requests sent to the following endpoint: https://your-api-domain/rcms-api/1/endpoint_name?p1=VALUE1&p2[]=VALUE2_0&p2[]=VALUE2_1&p3[k1]=VALUE3_1&p3[k2]=VALUE3_2

The following value will be set in $url:

$url

{
  "path": "/rcms-api/1/endpoint_name"
  "query": {
    "p1": "VALUE1",
    "p2": [
        "VALUE2_0",
        "VALUE2_1"
    ],
    "p3": {
        "k1": "VALUE3_1",
        "k2": "VALUE3_2"
    }
  }
}

$body

This variable references the components of the URL specified by the client.
It contains the same value as $smarty.post.

Variable name	Type	Description
$body	object	Endpoint's request body

Variables for API control

The following variables are not declared at the time the pre-process runs.
Initialising them and populating them with values allows you to control the behavior of the endpoint.

Variable name	Usage
$http_code	HTTP response codes handling
$errors	Custom error handling
$request	Modify API endpoint's request body

caution

Do not declare these variables for any purpose other than their intended one within the pre-processing custom function, as this may lead to to unintended behavior of the API endpoints.

$http_code

This is a variable used to control the HTTP response codes output by the endpoint.

The available HTTP codes are as follows.

Code	Name	Meaning
400	Bad Request	The request from the client is invalid.
401	Unauthorized	The request failed due to lack of user authentication (not logged in).
403	Forbidden	The request failed because the user does not have access rights to the content (different from 401, as user authentication is completed).
404	Not Found	The request failed because the specified endpoint's content does not exist.
408	Request Timeout	Error that occurs when the request times out.
500	Internal Server Error	Error that occurs when the request from the client is correct, but an error occurs on the server side.

Code example

{if `error checking process`}
  {assign var=http_code value=404}
  {assign_array var=errors values=''}
  {assign var=errors. value='The content does not exist.'}
{/if}

$errors

This variable can be used to perform custom error handling in the endpoint.

You can implement your own validation process on the endpoint by determining the input value and storing the resulting error message in an array.

Variable name	Type	Initial value	Description
$errors	object	null	API endpoint's error codes and messages

Code example

{* Initialize it as an empty array. *}
{assign_array var='errors' values=''}
{* Validate input value. *}
{if $smarty.post.key_name === 'VALUE'}
  {* Add error message in the array. *}
  {assign var='errors.' value='An error has occurred.'}
{/if}

Error response format

HTTP status code	errors[].code	errors[].message
422	unprocessable_entity	Messages stored in errors object

ExampleResponse

// Response example
{
  "errors": [
    {
      "code": "unprocessable_entity",
      "message": "An error has occurred."
    }
  ],
  "x-rcms-request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxx"
}

If $errors object contains more than 1 element, the response format is as follows:

errors

[
  {"code": "unprocessable_entity", "message": "messages stored in errors object"}
]

If the $errors array contains multiple element, an object is outputted for each of the errors.

errors

[
  {"code": "unprocessable_entity", "message": "error message 1"},
  {"code": "unprocessable_entity", "message": "error message 2"},
  // ...
]

$request

This variable can be used to modify the request values passed to the pre-process custom function.

Variable name	Type	Initial value	Description
$request	object	null	Custom request body for the pre-processing

By setting a value in this variable in the following format, you can add or overwrite the request value (GET / POST) to be passed to the pre-process custom function.

{assign var='request.***(target key name)' value='***(value)'}

To set the value based on the existing request value from the API endpoint, use the following reference variable.

Variable name	Remark
$url.query	Alternative variable name: $smarty.get
$body	Alternative variable name: $smarty.post

Code sample

{* Initialize as empty array *}
{assign_array var='request' values=''}

{* Determine if there is a request value *}
{if $url.query.filter}
  {* overwrite query parameter *}
  {assign
    var='request.filter'
    value="`$url.query.filter AND topics_id in [1, 2, 3]"}
{/if}

Reference tutorial

Here is the tutorial on how to implement a pre-processing:

• How to implement original validation in API by using custom functionn

Troubleshooting

If the pre-processing is not working as expected, check the following points:

• Check if the API pre-processing is associated with the custom function properly.
• Check if the associated custom function is correct.
• Check if the variable names are correct.
• Check if the data format stored in the variables are correct.
• Check if the custom function syntax is correct.