The Remote Job Submission API enables integration of Charity Engine as a backend service and provides functions for managing the entire lifecycle of jobs submitted to the network.

Contents

General Usage

The endpoint for all calls is: https://api.charityengine.services/remotejobs/v2/ 

The endpoint accepts a JSON payload within a POST request, unless otherwise specified.

Also see External APIs, which lists APIs that the Remote API is able to call.

API definition

External APIs (draft)

Charity Engine can call the following API endpoints upon circumstances outlined in this document. An HTTP POST request with JSON payload will be dispatched to a URL hosted by the compute provider or other external services.

HTTP Basic authorization for API endpoint URLs is supported.

compute-launch

When compute capacity is purchased on the Charity Engine marketplace, Charity Engine can call a compute provider’s API endpoint to launch reserved compute capacity.

Parameters

ComputeCapacity[] capacity // List of ComputeCapacity objects, one per instance type that is being reserved.
float duration // Maximum number of hours the compute capacity is reserved for. Compute payloads may exit early. 

Expected results

int count // Number of successfully launched instances.
string error // Error message, if any. Optional.

Testing + Troubleshooting

Testing via CURL

To use cURL to submit a job from a .json file:

$ curl -v "content-type: application/json" https://api.charityengine.services/remotejobs/v2/job-create -d @example-job-create.json

Contents of the POST data (example-job-create.json file):

{
  "authenticator":"c503d86bc4e82d9415cb5912a0986c80",
  "app":"charityengine:wolframengine",
  "commandLine":"math 2+2 > output/out.txt",
  "specs": {
    "vcpus":2,
    "ram": 512,
    "disk": 512,
    "networkDownload": 0,
    "networkUpload": 0
  },
  "hours": 1,
  "inputFiles": [
    {
      "filename": "in.txt",
      "url": "http://work.charityengine.com/rytis/mathtest.m"
    }
  ]
}

Troubleshooting

If trouble occurs on the execution node, it can be helpful to set the useOwnDevices parameter to true during job-create. This causes the job to be given to a node operated by the account that submitted the job, rather than sending it out to other qualified nodes in the Charity Engine device pool.