Can I send files to an external API with the api plugin?

Yes. When you specify POST in method and temporary files in files of the api plugin, the files are sent to the external API as multipart/form-data.

There are two methods, depending on the file you send.

• Send a file stored in Kuroco
• Relay a file received by Api::request_api_post

How to specify the files attribute

In files, specify an associative array keyed by form field names. Each element has the following values.

Key	Description
path	Path of the temporary file to send (relative path from the Kuroco temporary folder)
name	File name used when sending

For example, to send a file to the external API with the field name file_input_name and the file name image.png, specify files in the following format.

[
  "file_input_name" => [
    "path" => "rcms_get_file_XXXXXX",
    "name" => "image.png"
  ]
]

To send multiple files, add an element for each field name.

When you specify queries, those values are also sent as form fields in the same request as the files.

Send a file stored in Kuroco

Fetch a file stored in KurocoFiles or other storage as a temporary file with get_file, and send it to the external API. The path of the fetched temporary file is stored in the var of get_file.

{* Fetch the file to send as a temporary file *}
{get_file path="/files/user/sample/image.png" var="tmp_path" status_var="get_file_result"}

{if $get_file_result}
    {* Get the credentials of the external API from secrets *}
    {secret var="api_token" key="EXTERNAL_API_TOKEN"}

    {assign_array var="headers" values=""}
    {append var="headers" value="Authorization: Bearer `$api_token`"}

    {assign_array var="file" values=""}
    {assign var="file.path" value=$tmp_path}
    {assign var="file.name" value="image.png"}

    {assign_array var="files" values=""}
    {assign var="files.file_input_name" value=$file}

    {api
        endpoint="https://api.example.com/upload"
        method="POST"
        headers=$headers
        files=$files
        json_var="response"
        status_var="status"
        http_code_var="http_code"
        timeout=10
    }
{/if}

A temporary file created with write_file can be sent in the same way by specifying the path stored in its var as path.

Relay a file received by Api::request_api_post

Send a file received by an Api::request_api_post endpoint to the external API without saving it in Kuroco. For how to create the endpoint and the custom function, see Creating a custom function endpoint.

For example, when a file is sent to an Api::request_api_post endpoint as follows:

curl -X 'POST' 'https://your-site.g.kuroco.app/rcms-api/1/custom_file_upload' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file_input_name=@image.png'

the received file is stored in $files of the called custom function. Each element of $files contains the following values (it also contains other values such as type and size). input_name is the field name of the request.

[
  [
    "path" => "request_api_postXXXXXX",
    "name" => "image.png",
    "input_name" => "file_input_name"
  ]
]

You can specify this $files as is in files of the api plugin. The file is sent to the external API with input_name as the field name and name as the file name.

{* Custom function called by Api::request_api_post *}
{secret var="api_token" key="EXTERNAL_API_TOKEN"}

{assign_array var="headers" values=""}
{append var="headers" value="Authorization: Bearer `$api_token`"}

{api
    endpoint="https://api.example.com/upload"
    method="POST"
    headers=$headers
    files=$files
    json_var="response"
    status_var="status"
    http_code_var="http_code"
    timeout=10
}

{if !$status}
    {append var="errors" value="Failed to send the file."}
{/if}

Notes

• files cannot be used with the api plugin when oauth_connection is specified. Store the credentials of the external API in Secrets and specify them in headers. Only superusers can save custom functions that contain the secret plugin.
• Temporary files under /files/temp/ uploaded with Files::upload or similar endpoints cannot be fetched with get_file, so they cannot be sent with these methods.
• An API request that runs a custom function is bounded by a PHP execution time of 30 seconds. Set timeout to less than 30 seconds. For details, see Execution time limit.

Related documents

• Smarty plugin (api)
• Creating a custom function endpoint
• Secrets