Executing Jobs

This document explains how to run jobs on a MikroTik router using both synchronous and asynchronous methods.

Synchronous Execution

The synchronous API is a wrapper around the MikroTik RouterOS native API. It allows you to make real-time API calls to the MikroTik via the management tunnel. This method is recommended for real-time read operations and not for configuration changes due to potential issues with delivery guarantees and idempotency.

The Synchronous API Object

Endpoint

POST /api/synchronous/{router_id}

Payload Example: Listing ARP

{
  "command": "/ip/arp/print"
}

Response Example

{
  "status": "success",
  "data": [
    {
      "id": "*1",
      "address": "192.168.88.254",
      "mac_address": "50:32:37:7B:93:49",
      "interface": "bridge",
      "published": "false",
      "invalid": "false",
      "DHCP": "false",
      "dynamic": "true",
      "complete": "true",
      "disabled": "false"
    }
  ]
}

Making Configuration Changes

While it is possible to make changes using the synchronous API, it is recommended to use the asynchronous API for such operations. If you choose to use the synchronous API, use the /execute command with =script= in the parameters for easier command syntax.

Example: Adding an IP Address

{
  "command": "/execute",
  "parameters": "=script=/ip address add address=10.0.0.1/30 interface=ether1 disabled=no"
}

Important Note

The synchronous API does not guarantee delivery and does not implement idempotent requests. This means you might add the same configuration twice if using queuing systems on your side. Use this API mainly for real-time read operations.

Asynchronous Execution

The asynchronous API allows you to trigger actions on a MikroTik router without waiting for an immediate response. This method is more reliable for configuration changes and tasks that do not need to be executed in real-time.

How the Asynchronous System Works

1. Job Submission: You submit a job to the API with a specific script and other optional parameters.
2. Job Processing: The job is queued and processed asynchronously. If express_execute is set to true, the job is executed immediately.
3. Notifications: You can provide a notify_url where the status of the job will be posted (e.g., loaded, running, completed, failed, or deleted).
4. Acknowledgment: If needs_acknowledgement is true, the system waits for acknowledgment before marking the job as completed.

Request Body

Endpoint

POST /api/asynchronous/{router_id}

Example Request

{
  "description": "Log test message",
  "script": ":log info test",
  "make_backup": false,
  "express_execute": false,
  "needs_acknowledgement": false,
  "notify_url": "https://example.com/notify"
}

Response Example

{
  "status": "success",
  "data": {
    "idempotency_key": "7bbb8378-1675-515d-8ef4-ddb784fd0e52",
    "request_id": "2859d7db-bd7f-5d0d-b973-89142ff7b202",
    "target": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "notify_url": "https://example.com/notify",
    "date": "2024-05-28T08:05:28+00:00"
  }
}

The Response Object

Notification Payload

When a job is executed asynchronously, the status of the job is posted back to the provided notify_url. The payload includes details about the job, its status, and other relevant information.

Example Payload

{
  "job_id": "00000000-0000-0000-0000-000000000001",
  "customer_id": "00000000-0000-0000-0000-000000000002",
  "description": "example description",
  "router_id": "00000000-0000-0000-0000-000000000003",
  "idempotency_key": "00000000-0000-0000-0000-000000000004",
  "express_execute": false,
  "needs_acknowledgement": true,
  "make_backup": false,
  "seq_id": 1234567890,
  "started_at": "2024-05-28T06:14:19+00:00",
  "completed_at": "2024-05-28T06:14:21+00:00",
  "failed_at": null,
  "deleted_at": null,
  "status": "completed"
}

Payload Object

Retrieve a List of Jobs

The /api/routers/{router_id}/jobs endpoint allows you to retrieve a list of jobs executed on a specific router. This can be useful for monitoring and managing the tasks performed on your MikroTik routers.

Endpoint

GET /api/routers/{router_id}/jobs

Sample Response

{
  "status": "success",
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "token": "exampleToken123",
      "idempotency_key": "00000000-0000-0000-0000-000000000002",
      "description": "Example Job Description",
      "express_execute": false,
      "needs_acknowledgement": true,
      "make_backup": false,
      "started_at": "2024-05-29T00:11:49+00:00",
      "completed_at": "2024-05-29T00:12:08+00:00",
      "failed_at": null,
      "deleted_at": null,
      "status": "completed"
    }
  ]
}