RESTful

Create/Update a Job#

Request

• Method: PUT

• URL: https://<host:port>/jobs/<namespace>/<name>

• Header: Content-Type: application/json

• Body:
  As follows are some of the fields. To learn more, view the Complete List of All Features → .

  {
    // schedule expression. can be a cron expression or a periodic expression
    "expr": "* * * * *",
    // regularly called on the specified schedule
    "callback": {
      // HTTP callback. optional.
      "http": { // HTTP Post request
        "url": "http://<host>/<path>",
        "header": { // optional
          "Content-Type": "application/x-www-form-urlencoded"
        },
        "body": "xda=lafayl&cet=hvesud" // optional
      },
      // or TCP callback. optional.
      "tcp": {
        // the TCP address to be connected
        "addr": "<host>:<port>",
        // the data to be sent. base64 encoded.
        "body": "qgBTpMtbXWnzVCXMv50OLA==",
        // the data expected to be received. base64 encoded.
        "ack": "LI67iYenlxY="
      },
      // optional
      "timeout": "3s",
      // number of retries. optional
      "retryTimes": 2,
      // the time to wait between retries. optional
      "retryInterval": "3s",
    },
    // limit how many times a job can be scheduled. optional
    "times": 12,
    // description. optional
    "memo": "..."
  }

Response

• OK
  • StatusCode: 200
  • Body: {"msg": "OK"}
• Invalid
  • StatusCode: 400
  • Body: {"msg": "<validation error>"}
• Unprocessable
  • StatusCode: 422
  • Body: {"msg": "<error>"}

Get a Job#

Request

• Method: GET
• URL: https://<host:port>/jobs/<namespace>/<name>

Response

• OK

  • StatusCode: 200
  • Body:

  {
    "ns": "<namespace>",
    "name": "<name>",
    "expr": "* * * * *",
    "callback": {
      "http": {
        "url": "http://<host>/<path>",
        "header": {
          "Content-Type": "application/x-www-form-urlencoded"
        },
        "body": "xda=lafayl&cet=hvesud"
      },
      "timeout": "3s",
      "retryTimes": 2,
      "retryInterval": "3s",
    },
    "times": 12,
    "memo": "...",
  }

• Not Found

  • StatusCode: 404
  • Body: {"msg":"not found"}

• Unprocessable

  • StatusCode: 422
  • Body: {"msg": "<error>"}

Delete a Job#

Request

• Method: DELETE
• URL: https://<host:port>/jobs/<namespace>/<name>

Response

• OK
  • StatusCode: 200
  • Body: {"msg": "OK"}
• Not Found
  Same as OK.
• Unprocessable
  • StatusCode: 422
  • Body: {"msg": "<error>"}

Get Job Execution History#

Request

• Method: GET
• URL: https://<host:port>/jobs/<namespace>/<name>/his

Response

• OK

  • StatusCode: 200
  • Body:

  {
    "ns": "<namespace>",
    "name": "<name>",
    // the number of times the job has been executed
    "times": 9,
    // the latest n (history size) execution records
    "records": [
      {
        "startAt": "2024-01-01T00:00:00Z",
        "endAt": "2024-01-01T00:00:00Z",
        "msg": "..." // error message if any
      },
      // ...
    ]
  }

• Not Found

  • StatusCode: 404
  • Body: {"msg":"not found"}

• Unprocessable

  • StatusCode: 422
  • Body: {"msg": "<error>"}

Host:Port#

<dcs-dns-name>:<port>.
<dcs-dns-name> is the DNS name generated by K8S for DCS,
and defaults to dcs.<namespace>.svc.cluster.local,
and can be abbreviated to dcs.<namespace>,
and can be abbreviated to dcs if the service which sends the request is deployed in the same namespace as DCS.
<port> defaults to 1058.

Mutual TLS Authentication#

DCS and client authenticate each other during TLS handshake.

Defend Against DDoS Attacks#

DCS limits max number of concurrent requests.

Meshless Mode#

Since v1.2.0 → , DCS Enterprise can communicate with other services via Meshless → .
You may choose to run DCS Enterprise in the standard mode or the new Meshless mode.

If you call DCS RESTful APIs in the Meshless mode, note the following differences between standard mode and Meshless mode.

See also Meshless Client User Guide →