Sync API
  • 14 Aug 2022
  • 2 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Sync API

  • Dark
    Light
  • PDF

postman Use our collection of Postman queries as an example

Purpose

Corezoid API is asynchronous - when requesting to create a new Task in a Corezoid Process, you receive the Task ID, not the Process output it invokes:

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

To receive the Task-invoked Process output, you need to implement synchronous responding.

Example:

Our job is 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.

Using Corezoid API for sending Tasks to a Corezoid Process, we 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.

Sync API Usage Specifics

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.

sync_api_callbackurl

Thus, you can use Sync API in a way similar to Corezoid API. To learn about Corezoid API use, see 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 incorrect signature

Request:

HTTP/1.1 401 Unauthorized
Date: Thu, 28 Oct 2021 14:31:40 GMT
Content-Length: 0
Connection: keep-alive
server: Cowboy
www-authenticate: Bad signature

Response (with no body):
401 Bad signature

Processing error (code 400)

Response to an incorrect body request:

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