Sync API

Overview

Corezoid API operates in the 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 to send tasks to a Corezoid process, you receive obj_id (Task ID) but not the requested process output, preventing you from developing the JS front-end.

By processing requests synchronously and using the Sync API module, you can receive requested outputs from Processes by sending requests via the Corezoid Sync API. Thus, Sync API serves the same purpose as the API Gateway.

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

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:

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

   

   Thus, you can use Sync API in a way similar to Corezoid API.
   Note: For more information on Corezoid API use, go to Corezoid API reference.

2. 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 for the specification of any status code within the 200 to 599 range in the Value field and returns it in the response.
   Note: All headers are always sent.

Example

Below is an 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}}

Where:

• {{API_LOGIN}}: Is the authorization login.
• {{GMT_UNIXTIME}}: Is the request time.
• {{SIGNATURE}}: Is the request signature.

Task creation request

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

Successful response

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

Error examples

As Sync API works with APIs, it mostly returns errors similar to Corezoid API. However, there are some Sync API-specific errors that you can see in 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"
          }
      ]
  }
  

• Request limit for a user is exceeded
  The following errors are proxied from CAPI and have the 200 code and N is the limit set for requests sent in a process for the process owner.

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

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