Pre-processing

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

tip

Since the processing implemented in Pre-processing is not reflected in the API information (Swagger UI) screen or openapi.json file, there might be a difference between the displayed information and the actual specifications. Therefore, it is recommended to describe the specifications of the customized part in the description of the endpoint.

Pre-processing setting methods

Pre-processing works according to the following procedure.

1. Write the program in the custom function
2. Associate the custom function with the endpoint settings

Each setting method's details are as follows:

Write the program in the custom function

Access Custom function editor page and create a custom function to implement a Pre-processing.

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

• Create a category for Pre-processing in advance and set it as the custom function category.
• Match the title of the custom function with the path name of the endpoint.

Associate the custom function with the endpoint settings

1. Access API LIST page

Select desired 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. Associate the custom function

Select a category and title(content) and associate the custom function which you created for the Pre-processing to the endpoint.

caution

Please note that if you make a mistake in the custom function to associate here, the endpoint may not work as expected.

Variables of Pre-processing

The variables used in Pre-processing contain reserved words with specific meanings. You can customize the behavior of the endpoint by using these variables.

variable	type
$meta	reference
$url	reference
$body	reference
$errors	API control
$request	API control

Variables for reference

The variables below are reference variables that are always assigned by default when Pre-processing works.
They're used to determine the endpoint information and the passed request value.

Variable name	Use
$meta	Meta information of endpoint
$url	URL component
$body	request body

$meta

It is a variable to refer to the meta information of the target endpoint.

Variable	Type	Description
$meta	array	Associative array

It consists of the following elements.

Key	Type	Initial value	Description
$meta.content_type	string		Content-type
$meta.mime	string		Content-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	array		API settings
$meta.post_json	string	GET: null POST: "{}"	JSON body in text format

$url

It is a variable to refer to the component of the URL specified by the client.

Variable name	Type	Description
$url	array	Associative array

It consists of the following elements.
Among these, $url.query contains the same value as $smarty.get.

Key	Type	Description
$url.path	string	path of the endpoint(except query parameter)
$url.query	array	Associative array which stores query parameter

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 is set in $url:

$url

[
  "path" => "/rcms-api/1/endpoint_name"
  "query" => [
    "p1" => "VALUE1",
    "p2" => [
        0 => "VALUE2_0",
        1 => "VALUE2_1"
    ],
    "p3" => [
        "k1" => "VALUE3_1",
        "k2" => "VALUE3_2"
    ]
  ]
]

$body

A variable to refer to the request body sent by the client.
It contains the same value as $smarty.post.

Variable name	Type	Initial value	Description
$body	array	request body	Associative array

Variables for API control

The variables below are the ones not declared by the time Pre-processing starts working.
You can control the endpoint's behavior by initializing these values and populating them.

Variable name	Use
$errors	to control errors
$request	to control request value

caution

Do not declare these variables for any purpose other than their intended one within the custom function of Pre-processing. The API endpoint may behave incorrectly otherwise.

$errors

It is a variable to control errors resulting from 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	array	null	text array

Code example

{* Initialize it by 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 array

SampleResponse

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

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

errors

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

If $errors array contains multiple elements, the number of objects for the number of errors is output:

errors

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

$request

It is a variable to control the request value which is passed to the main process.

Variable name	Type	Initial value	Description
$request	array	null	Associative array

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 main process.

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

To set the value based on the already specified request value, use the following reference variable.

Variable name	Remark
$url.query	Can be replaced with $smarty.get
$body	Can be replaced with $smarty.post

Code sample

{* Initialize by 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 for using Pre-processing:

• How to implement original validation in api by using custom function

When in trouble

If the Pre-processing does not work as expected, please check the following points:

• Whether the API Pre-processing is associated with the custom function properly.
• Whether the associated custom function is the correct one.
• Whether the variable name is correct.
• Whether the data format stored in the variable is correct.
• Whether the custom function syntax is correct.