Karajo HTTP APIs

Overview

The karajo service is an HTTP server. Its provide HTTP APIs to interact with the system. The following sub-sections describe each HTTP APIs request and response.

All HTTP response is encoded in the JSON format, with the following wrapper,

{
        "code": <number>,
        "message": <string>,
        "data": <array|object>
}

  • code: the response code, equal to HTTP status code.

  • message: the error message that describe why request is fail.

  • data: the dynamic data, specific to each endpoint.

Schemas

Environment

JSON format,

{
	"jobs": {<Job.Name>: <Job>, ...},
	"http_jobs": {<JobHttp.Name>: <JobHttp>, ...},

	"name": <string>,
	"listen_address": <string>,
	"dir_base": <string>,
	"dir_public": <string>,

	"http_timeout": <number>,
	"max_job_running": <number>,
	"is_development": <boolean>
}

  • jobs: list of Job.

  • http_jobs: list of JobHttp.

  • name: the karajo server name.

  • listen_address: the address where karajo HTTP server listening for request.

  • dir_base: The path to directory used as working directory.

  • dir_public: The path to directory served to public.

  • http_timeout: default HTTP timeout for job in nano-second.

  • max_job_running: default maximum job running at the same time.

  • is_development: true if current karajo server run for testing.

Job

JSON format,

{
	"last_run": <RFC3339_time>,
	"next_run": <RFC3339_time>,
	"id": <string>,
	"name": <string>,
	"description": <string>,
	"status": <"success"|"fail">,
	"interval": <number>,

	"logs": [<JobLog>, ...],
	"path": <string>,
	"auth_kind": <string>,
	"header_sign": <string>,
	"commands": [<string>, ...],
	"log_retention": <number>
}

  • last_run: Date and time when the job last run, in the format RFC3339,

  • next_run: Date and time when the next job will be executed, in the format RFC3339.

  • id: Unique job ID

  • name: Human representation of job name.

  • description: Job description, can be HTML.

  • status: Status of the last job running, its either "started, "success", "failed", or "paused".

  • interval: A period of nano-seconds when the job will be executed.

  • logs: List of job log per execution.

  • path: HTTP path where Job can be triggered using HTTP.

  • auth_kind: The kind of authorization to trigger Job.

  • header_sign: Custom HTTP header where the signature is read.

  • commands: List of command to be executed.

  • log_retention: The maximum number of logs to keep in storage.

JobLog

JSON format,

{
	"job_id": <string>,
	"name": <string>,
	"status": <string>,
	"content": <base64>,
	"counter": <number>
}

  • job_id: The ID of Job that own the log.

  • name: The Name of log in the format JobID.Counter.Status.

  • status: The status of job, its either "success" or "fail".

  • content: The content of log.

  • counter: The log number.

JobHttp

JSON format,

{
	"last_run": <RFC3339_time>,
	"next_run": <RFC3339_time>,
	"id": <string>,
	"name": <string>,
	"description": <string>,
	"status": <string>,
	"interval": <number>,

	"http_method": <string>,
	"http_url": <string>,
	"http_request_type": <string>,
	"http_headers": [<string>],
	"http_timeout": <number>,
	"http_insecure": <boolean>
}

  • last_run: Date and time when the job last run, in the format RFC3339,

  • next_run: Date and time when the next job will be executed, in the format RFC3339.

  • id: Unique job ID

  • name: Human representation of job name.

  • description: Job description, can be HTML.

  • status: Status of the last job running, its either "started, "success", "failed", or "paused".

  • interval: A period of nano-seconds when the job will be executed.

  • http_method: The HTTP method used to invoke the http_url.

  • http_url: The URL where job will be executed.

  • http_request_type: The request type for HTTP.

  • http_headers: List of string, in the format of "Key: Value", which will be send when invoking the job.

  • http_timeout: A timeout for HTTP request, in nano-second.

  • http_insecure: If true, the request to server with unknown certificate will be ignored.

Get environment

Get the current karajo environment.

Request

GET /karajo/api/environment

Response

On success, it will return the Env object,

{
	"code": 200,
	"data": <Env>
}

Pause job

Pause the Job for being executed. Any HTTP request that trigger the job after paused will return 412 Precondition Failed.

Request

POST /karajo/api/job_exec/pause
Content-Type: application/x-www-form-urlencoded

_karajo_epoch=&id=

Response

List of know response,

  • 200: OK, if job ID is valid.

  • 404: If job ID not found.

Resume job

Resume the Job execution.

Request

POST /karajo/api/job_exec/resume
Content-Type: application/x-www-form-urlencoded

_karajo_epoch=&id=

Response

List of know response,

  • 200: OK, if job ID is valid.

  • 404: If job ID not found.

Get job log

HTTP API to get the Job log by its ID and counter.

Request

GET /karajo/api/job_exec/log?id=<jobID>&counter=<logCounter>

Parameters,

  • jobID: the job ID

  • logCounter: the log number.

Response

On success, it will return the JobLog object as JSON.

Get JobHttp detail

HTTP API to get a JobHttp information by its ID.

Request

GET /karajo/api/job_http?id=<string>

Parameters,

  • id: the job ID.

Response

On success, it will return the JobHttp schema.

On fail, it will return

  • 400: for invalid or empty job ID

Get JobHttp logs

Get the last JobHttp logs by its ID.

Request

GET /karajo/api/job_http/logs?id=<string>

Parameters,

  • id: the job ID.

Response

On success it will return list of string, contains log execution and the response from executing the http_url.

On fail, it will return

  • 400: invalid or empty job ID.

Pause the JobHttp

Pause the JobHttp timer by its ID.

Request

The request is authorization using signature.

Format,

POST /karajo/api/job_http/pause?id=<id>
X-Karajo-Sign: <query signature>

Parameters,

  • id: the job ID.

Response

On success it will return the JobHttp schema with field Status set to paused.

On fail it will return

  • 400: invalid or empty job ID.

Resume the JobHttp

HTTP API to resume paused JobHttp by its ID.

Request

The request is authorization using signature.

Format,

POST /karajo/api/job_http/resume?id=<id>
X-Karajo-Sign: <query signature>

Parameters,

  • id: the job ID.

Response

On success it will return the JobHttp schema related to the ID with field Status reset back to started.

Powered by ciigo