Containers
API - Quickstart

This tutorial will show you how to start using the Containers module API. For general information about the API, go to the Containers Module API Overview. For technical details on API methods, go to the API Reference Version 1.1.

Step 1: Accessing the endpoint

The Sphere Engine Containers API is available at:

https://<customer_id>.containers.sphere-engine.com/api/v1

To call an API method, you need to be authenticated with an API token that you can generate in the Token Manager section of the Sphere Engine client panel.

You can check if the token is correct by using the /test method:

https://<customer_id>.containers.sphere-engine.com/api/v1/test?access_token=<access_token>

Step 2: Prepare a submission file

A typical submission to the Sphere Engine Containers API is a part of a bigger project. Such submissions are usually packages containing many files distributed in a directory tree.

Here is an example structure of a submission:

src
  models
    Bookstore.ts
    User.ts
  views
    Library.tsx

Our intention is to create a tar.gz archive containing all the files (i.e., Bookstore.ts, User.ts, Library.tsx) and preserve the directory structure. As a convention, we require the archive to have a canonical form in which there is a single directory named workspace in the root of this archive. All submission files should be placed inside the workspace directory.

Assuming we are in the directory directly above src, we can do it as follows:

tar -czf source.tar.gz --transform 's,^,workspace/,' ./src

This should generate the source.tar.gz archive ready to be submitted via the API method. The archive yields the following structure (note the added workspace directory in the root of the directory structure):

workspace
  src
    models
      Bookstore.ts
      User.ts
    views
      Library.tsx

For your convenience, we have already prepared a file that you can download here. You can use it to skip this step entirely or as a reference while preparing your own archive.

Step 3: Creating a submission

The following example shows how to call the API method responsible for creating a new submission using the curl command. Having completed the previous step, we already have an archive source.tar.gz with the source code files inside. Now, we can call the API method in the following way:

curl -X POST \
  -F "project_id=EXAMPLE" \
  -F "scenario=run" \
  -F "source=@source.tar.gz" \
  "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions?access_token=<access_token>"

The above command (see details on this API method) sends a tar.gz archive (i.e., the source.tar.gz file we’ve created before) as a part of the submission to the "EXAMPLE" project (i.e., project_id=EXAMPLE).

The response from the API call will be a unique identifier of the submission, for example:

{
  "message": "Submission has been created",
  "id": 42
}

Step 4: Checking the result

After sending a submission, wait a while for it to be executed. While waiting, you may also check the submission's current status every few seconds (learn more).

You can receive the submission’s execution results with the following API method. Note the submission identifier used as a parameter (42 in the below example):

curl "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42?access_token=<access_token>"

If the submission is fully processed, the Sphere Engine Containers API will return the final execution results. An example API response may look as follows:

{
  "id": 42,
  "executing": false,
  "date": "2022-01-01 14:21:57 +0000",
  "project": {
    "id": "abcdefghxyz",
    "name": "EXAMPLE"
  },
  "scenario": "run",
  "result": {
    "status": {
      "code": 15,
      "name": "ok"
    },
    "score": 0,
    "time": 1.23,
    "memory": 239421,
    "signal": 0
  },
  "streams": {
    "source": {
      "size": 88,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/source"
    },
    "auxdata": {
      "size": 105,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/auxdata"
    },
    "tests_report": {
      "size": 8774,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/tests_report"
    },
    "debug_log": {
      "size": 142,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/debug_log"
    },
    "stage_init_output": {
      "size": 97,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/stage_init_output"
    },
    "stage_init_error": null,
    "stage_build_output": {
      "size": 80,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/stage_build_output"
    },
    "stage_build_error": null,
    "stage_run_output": {
      "size": 1134,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/stage_run_output"
    },
    "stage_run_error": {
      "size": 567,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/stage_run_error"
    },
    "stage_test_output": {
      "size": 900,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/stage_test_output"
    },
    "stage_test_error": null,
    "stage_post_output": {
      "size": 97,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/stage_post_output"
    },
    "stage_post_error": null,
    "workspace_init_output": {
      "size": 253,
      "uri": "https://<customer_id>.containers.sphere-engine.com/api/v1/submissions/42/workspace_init_output"
    },
    "workspace_init_error": null
  },
  "stages": {
    "init": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "build": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "run": {
      "time": 4.2,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "test": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "post": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    }
  }
}