Sync API

Why use Sync API

Corezoid API operates in an asynchronous mode when requesting a new task creation in a Corezoid process. This means that in the response you receive a task ID, not the process output it invokes:

{
    "request_proc": "ok",
    "ops": [
        {
            "id": "",
            "proc": "ok",
            "obj": "task",
            "ref": "ref",
            "obj_id": "5d1b6ee5f6c37653b9904f7d"
        }
    ]
}

For example, you need to implement the logic of P2P money transfer from client A to client B on a website that consists of:

• JS front-end without business logic.
• Corezoid back-end that manages the business logic.

If you use the Corezoid API for sending tasks to a Corezoid process, you will receive obj_id (Task ID) but not the requested process output, which prevents you from developing the JS front-end.

To receive a task-invoked process output, you must implement the synchronous response.

With the release of version 4.2, Corezoid introduced a support for synchronous processing of requests. This is facilitated using the Sync API module. With this update, you can receive requested outputs from Processes by sending requests via the Corezoid Sync API.

Use our collection of Corezoid Sync API queries for Postman as an example

With that, Sync API serves the same purpose as the API Gateway.

Sync API protocol

The Sync API protocol is compatible with the API Gateway protocol.

For the Sync API protocol, the following task format is used:

{
    "__callback_url": "https://url...",
    "__headers": {
        "user-agent": "curl/7.87.0"
    },
    "incKey": 12345
}

Things to keep in mind when using Sync API

1. When sending a request via Sync API, the __callback_url system parameter is automatically included in the task. This parameter keeps a link to a caller service, to which Corezoid should respond:

"__callback_url": "https://sync-api.corezoid.com/api/1/plugins/callback/{{request_id}}"

To configure a synchronous response, you need to:

a. Add the API Call node at the Process step which should send a requested output to a caller service.
b. Provide the {{__callback_url}}.
c. Specify the parameters which will be sent to the caller service.

Thus, you can use Sync API in a way similar to Corezoid API.
For more details on Corezoid API use, see the Corezoid API reference.

2. You can specify the X-Status-Code key in the Other->Header parameters of the Corezoid node from which the response is sent to the callback URL. This key allows specifying any status code within the 200 to 599 range in the Value field and returning it in the response.

Example of a task creation request to Sync API from an external service

URL

https://sync-api.corezoid.com/api/1/json/{{API_LOGIN}}/{{TIMESTAMP}}/{{SIGNATURE}}

• {{API_LOGIN}} - authorization login
• {{GMT_UNIXTIME}} - request time
• {{SIGNATURE}} - request signature

Request time should be Unix time: number of seconds elapsed from the Unix epoch at the GMT+0 Time Zone.

A mandatory request signature is created according to the standard Corezoid API protocol.

You need to grant access to Task management to an API key, which login and password are used in the request.

Task creation request

{
    "timeout": 30,
    "ops": [{
        "conv_id": {{CONV_ID}},
        "type": "create",
        "obj": "task",
        "data": {
            "param": 1
        }
    }]
}

*See the license agreement

**A Task is limited to a size specified in a configuration file.

Successful response

{
    "ops": [
        {
            "proc": "ok",
            "data": {
                "info": {
                    "param_1": "value_1",
                    "param_2": "value_2",
                    "param_3": "value_3"
                }
            }
        }
    ],
    "request_proc": "ok"
}

To see examples of creating tasks by Alias with Sync API, see the Postman queries collection available by the link above and the API section.

Error examples

As Sync API works with APIs, it mostly returns errors similar to Corezoid API. However, there are some Sync API-specific errors. See the examples below.

Response to a request from an API key with an incorrect signature

{
  "request_proc": "ok",
  "ops": [
    {
      "proc": "error",
      "description": "Bad signature"
    }
  ]
}

Response to an incorrect body request (code 400)

{
    "request_proc":"ok",
    "ops": [
        {
        "proc": "error",
        "description": "Incorrect body"
        }
    ]
}

Response was not received in the specified period (code 200)

The timeout parameter allows setting the period for response waiting. In case the response was not received in the period specified, the following error is generated:

{
    "request_proc": "ok",
    "ops": [
        {
            "proc": "error",
            "description": "Timeout for create task"
        }
    ]
}

The following errors are proxied from CAPI and have the 200 code

Request limit for a user is exceeded

{
    "request_proc": "ok",
    "ops": [
        {
            "proc": "error",
            "description": "too many requests, you exceeded user limit N/sec"
        }
    ]
}

where N is the limit set for requests sent in a process for the process owner.

Examples of validation and integrity check errors

Conveyor is not active

{
    "request_proc": "ok",
    "ops": [
        {
            "proc": "error",
            "description": "conveyor is not active"
        }
    ]
}

Non-unique REF parameter value

{
    "request_proc": "ok",
    "ops": [
        {
            "proc": "error",
            "description": "not_unical_ref"
        }
    ]
}

Access for api_copy is denied

{
    "request_proc": "ok",
    "ops": [
        {
            "proc": "error",
            "description": "access_denied"
        }
    ]
}

Conveyor was not found

{
    "request_proc": "ok",
    "ops": [
        {
            "proc": "error",
            "description": "conveyor not found"
        }
    ]
}