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 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"
        }
    ]
}

To receive a task-invoked process output, you need to implement the synchronous responding - use Sync API.

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.

We can't develop the JS front-end following this approach because we receive no output from business processes at the back end.
Since version 4.2, Corezoid supports the synchronous processing of requests using the Sync API module. Now, you can receive requested outputs from Processes by sending requests via Corezoid Sync API.

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

Things to keep in mind when using Sync API

When sending a request via Sync API, a task gets automatically the __callback_url system parameter. 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 synchronous response, you need to:

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

Thus, you can use Sync API in a way similar to Corezoid API. To learn more about Corezoid API use, see the Corezoid API reference.

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.

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"
        }
    ]
}