Post-processing

Post-processing refers to any user-defined processes performed on the default endpoint output after the main API process has been executed.

tip

Since such processes are not reflected in the API information (Swagger UI) screen or openapi.json file (for OpenAPI users), there may be differences between the displayed information and the actual specifications. Therefore, we recommend that you note the custom specifications in the endpoint description.

You can access the post-processing settings for each endpoint by clicking [Post-processing] in the corresponding row:

Post-processing settings

Post-processes are broken down into blocks. You may define any number of processing blocks, which will be executed in a series based on the order of definition.
Each block takes the results of the execution of the previous block as input. Click [Add] to append a new empty block at the end of the series.

info

The output allow list, when executed before other processes (such as custom processing), also affects internal processes like SQL.
Since it can improve performance, it is recommended to set the output allow list at the highest level whenever possible.

Block types

Currently, Kuroco supports three types of blocks:

Block name	Description
Allow list	Whitelist filter. Define a list of fields to retain in the output - all other fields will be omitted.
Convert list	Option to remove a field, rename its key, and/or to apply a function (from the list of predefined functions) to its value.
Custom function	Write the program as a function and link it to the endpoint (similar to post-processing).

See below for the details of each type.

Allow list

The allow list is a simple field filter. A list or details API returns a lot of information, some of which you may wish to make optional or hidden from users.

You can think of it as a whitelist: only the fields you set here will be returned. Therefore, you should list all the fields used by your front-end application.

tip

For a blacklist feature instead of a whitelist, see Convert list.

Field settings

Specify the full path to the field in the JSON output, starting from the root. Skip over arrays and only specify objects - the filter will be applied to all objects in an array.

tip

If your allow list does not specify any field or contains an error in the path name, the endpoint will output an empty JSON object.

Example scenario

Original Output

{
  "list": [
    {
      "subject": "First article",
      "contents": "The contents of the first article",
      "sponsors": ["Company X"]
    },
    {
      "subject": "Second article",
      "contents": "The contents of the second article",
      "sponsors": ["Company Y"]
    }
  ],
  "pageInfo": {
    "totalCnt": 7,
    "pageNo": 1,
    ...
  }
}

For example, in the above sample code, we would like to remove sponsors only.

The three fields we are keeping, including all root and child fields, are:

• list.subject
• list.contents
• pageInfo

Your configuration should look like this:

tip

Make sure to denote nested JSON objects using . and ignore all arrays.

The drawback to this simple filter is a lack of flexibility. If you need more in-depth customization, see Convert list and Custom function.

Convert list

This block allows you to add processes to each field by choosing among available options.

Click [Add field] to add a sub-block defining a process for a specific field. Note the two different [Delete] functions in this block: the one to the right (a) deletes the corresponding sub-block row, while the one at the bottom (b) deletes the entire block.

Field settings

Field	Description
Field	Specify the field path in the same way as for allow lists, using dot-separated nested objects and skipping over lists. The filter will be applied to all elements in a list. Note: If you enter a non-existent field, a new field with this name will be created under the specified parent. Therefore, you can use convert lists to easily add custom static data to your API.
Remove/copy field	Remove: Enabled this option to remove this field from the response. All other transformations for this sub-block row will be disabled. Select this option and fill in "New name" to create a new field with the specified process. Note: The original field with its original value will be preserved.
New name	Specify the new name of the field. A field with the new name will be added to the same parent object. Note: This is NOT a path, and you cannot use dot notation to set a different nested structure from the original field. For example, an identity transformation of a.b.c.d would simply be d, and you do not need to specify a new name in this case.
Process	Select one or more optional transformation(s) to apply to the field. In cases of multiple transformations, they will be applied in the order of selection. The specific actions of each process are listed below. To remove a process, click [-] next to it.
Delete	Remove the current processing sub-block.

Transformation processes

Process name	Action(s)
Null	Copy the original value as is (no transformation).
Truncate	Truncate the value to a maximum of N characters. Specify the length in the input box on the right. Warning: If left blank (or set to 0), the max length will default to 10.
Trim	Remove all spaces/tabs from the start and the end of the string. Warning: This function will convert the value into string format.
Strtotime	Apply the strtotime PHP function to the value.
Date format	Apply the date PHP function to the value to format it as a Unix timestamp.
Locale Date Format	Apply the specialized pg_dateformat function to the value.
Uppercase	Cast every character to its uppercase variant, if any.
Lowercase	Cast every character to its lowercase variant, if any.
Sprintf	Apply the sprintf PHP function to the input. The existing value is used as a second argument, which you can access using %s or other specifiers.
Nl2br	Insert <br /> before all new lines (\n, \r and \r\n) in a string. Useful when rendering to html.
FileSize	Retrieve the bytesize of a file if it exists at the specified path.
ImageSize	Retrieve the bytesize of an image if it exists at the specified path.

Example scenario

Consider the same sample code as before:

Original Output

{
  "list": [
    {
      "subject": "First article",
      "contents": "The contents of the first article",
      "sponsors": ["Company X"]
    },
    {
      "subject": "Second article",
      "contents": "The contents of the second article",
      "sponsors": ["Company Y"]
    }
  ],
  "pageInfo": {
    "totalCnt": 7,
    "pageNo": 1,
    ...
  }
}

Suppose you want to add a new field called title, which contains the uppercase version of the contents of subject. Configure your field settings as follows:

Field	Description
Field	list.subject
Remove/copy field	Select "Copy".
New name	title
Process	Uppercase

Your configuration should look like this:

New output:

Filtered Output

{
"list":
  [
    {
      "subject": "First article",
      "contents": "The contents of the first article",
      "sponsors": [
        "Company X"
      ],
      "title": "FIRST ARTICLE"
    },
    {
      "subject": "Second article",
      "contents": "The contents of the second article",
      "sponsors": [
        "Company Y"
      ],
      "title": "SECOND ARTICLE"
    }
  ],
"pageInfo":
  {
    "totalCnt": 7,
    "pageNo": 1
  }
}

Custom function

If your API requires more in-depth features, write a custom function defining how your data should be transformed and link it to your endpoint.

Custom function creation

Please create a custom process to be used in post-processing, referring to the custom processing as a reference.

To avoid confusion with custom functions used in other modules, we recommend setting it up as follows:

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

Linking the function to the target endpoint

1. In the left sidebar menu, click [API] and select the target endpoint list screen.
2. Select the target endpoint from the list and click [Post-processing].
3. In the dropdown list, select [Custom function] and choose the correct category and function name (list).
4. Click [Save].

caution

Double check to make sure you have linked the function correctly. If you made a mistake, the endpoint may not work as expected.

Example configuration:

Post-Processing Variables

There are reserved keywords with special meanings among the variables used in post-processing. By using these variables, you can customize the behavior of the endpoint.

Variable Name	Type
$json	Reference
$processed_json	API Control
$errors	API Control
$http_code	API Control

Reference Variables

Assigned Variables

The following variables are reference variables that are always assigned by default when post-processing is executed.

Variable Name	Type	Description
$json	object	The original JSON output of the API

Request Variables

To handle request variables in post-processing, use the following syntax:

• GET variables: $smarty.get.hoge
• POST variables: $smarty.post.foo

Additionally, you can use combined request variables:

• Request variables: $smarty.request.piyo

{assign var="message" value="Hello "|cat:$smarty.request.name}
{assign var="data" value=$message}

Variables for API Control

Variable Name	Requirement	Type	Description
$processed_json	Required	object	Assign the JSON value to be returned as the response to this variable.
$errors	Optional	object	If you assign a value to this variable, the endpoint will return an error. The assigned value will be used as the message field in the response.
$http_code	Optional	int	When a value is assigned to errors, assigning a value to this variable will override the original HTTP code.

The available HTTP status codes are as follows:

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

When in trouble

If a post-process is not working as expected, verify the following:

• The post-processing custom function has been linked properly.
• You have linked the correct custom function.
• The variable name is correct.
• The variable data is stored in the correct format.
• The custom function contains no syntax errors.