Pre-processing

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

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 function
  2. Associate the function with the endpoint settings

Each setting method's details are as follows:

Write the program in the function

Access Function edit page and create a function to implement a Pre-processing.

Image (fetched from Gyazo)

To avoid confusion with 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 function category.
  • Match the title of the function with the path name of the endpoint.

Associate the function with the endpoint settings

1. Access API LIST page

Select desired API on the side menu and access API LIST page.

Image (fetched from Gyazo)

2. Select the endpoint

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

Image (fetched from Gyazo)

3. Associate the function

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

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

Image (fetched from Gyazo)

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.

variabletype
$metareference
$urlreference
$bodyreference
$errorsAPI control
$requestAPI 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 nameUse
$metaMeta information of endpoint
$urlURL component
$bodyrequest body

$meta

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

VariableTypeDescription
$metaarrayAssociative array

It consists of the following elements.

KeyTypeInitial valueDescription
$meta.content_typestringContent-type
$meta.mimestringContent-type
$meta.mime.typestringMIME type
$meta.mime.subtypestringMIME sub-type
$meta.output_formatstring"json"_output_format specified in query parameter
$meta.langstringDetermined based on the following priorities:
[browser language > main language settings]
_lang specified in query parameter
$meta.charsetstring"utf8"_charset specified in query parameter
$meta.http_codestringnull
$meta.api_headerarrayAPI settings
$meta.post_jsonstringGET: 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 nameTypeDescription
$urlarrayAssociative array

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

KeyTypeDescription
$url.pathstringpath of the endpoint(except query parameter)
$url.queryarrayAssociative array which stores query parameter

e.g: If the request is 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/preprocess-test"
  "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 nameTypeInitial valueDescription
$bodyarrayrequest bodyAssociative 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 nameUse
$errorsto control errors
$requestto control request value

Do not declare these variables for any purpose other than their intended one within the 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 nameTypeInitial valueDescription
$errorsarraynulltext 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 codeerrors[].codeerrors[].message
422unprocessable_entitymessages 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 nameTypeInitial valueDescription
$requestarraynullAssociative 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 nameRemark
$url.queryCan be replaced with $smarty.get
$bodyCan 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:

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 function properly.
  • Whether the associated function is the correct one.
  • Whether the variable name is correct.
  • Whether the data format stored in the variable is correct.
  • Whether the function syntax is correct.