Harthelm Docs
REST APILandscape

Get the landscape

The synced landscape: state, profile, `spec_hash`, the run switch and one entry per service with its observed status. An empty landscape has no services. Needs `workspace.view`. The `ETag` is the quoted `spec_hash` (`"empty"` before the first Sync).

Generated from openapi/harthelm.yaml at v1.5.0
GET
/workspaces/{ws}/landscape

Authorization

cookie__Host-harthelm_session<token>

Browser session of the UI (12 h idle, 7 days absolute). State-changing requests also need the header Harthelm-CSRF: 1 and a matching Origin.

Path Parameters

ws*integer

Numeric resource id.

Formatint64
Range1 <= value

Response Body

The landscape.

application/json
  1. response
workspace_id*ID

Numeric resource id.

Formatint64
Range1 <= value
state*LandscapeState
Value in"empty""synced""torn-down"
profile?ProfileName

The profile of the last Sync.

Match^([a-z0-9]([-a-z0-9]{0,30}[a-z0-9])?)?$
selected_profile?ProfileName

The profile of the last Sync.

Match^([a-z0-9]([-a-z0-9]{0,30}[a-z0-9])?)?$
spec_hash?string

Hash of the synced, resolved spec; absent while empty.

source_hash?string

SHA-256 of the file the last Sync read; compare with a plan's file.sha256 for the out-of-sync banner.

source_commit?string

HEAD of /data/app at the last Sync.

generation*integer

Bumped by every Sync and Teardown.

Formatint64
synced_at?string
Formatdate-time
synced_by?ID

Numeric resource id.

Formatint64
Range1 <= value
run_state*RunState

started: the steps run, also after a pod restart or a wake; stopped: the pods stay, the steps do not run.

Value in"stopped""started"
run_generation*integer

Bumped by every Run.

Formatint64
operation_id?string

The landscape.sync or landscape.teardown operation in progress.

Formatuuid
services*array<>
curl -X GET 'https://console.example.com/api/v1/workspaces/1/landscape'
{  "workspace_id": 1,  "state": "empty",  "profile": "string",  "selected_profile": "string",  "spec_hash": "string",  "source_hash": "string",  "source_commit": "string",  "generation": 0,  "synced_at": "2019-08-24T14:15:22Z",  "synced_by": 1,  "run_state": "stopped",  "run_generation": 0,  "operation_id": "cb4ede3c-a5d1-45e3-a9d2-fe83accbce52",  "services": [    {      "name": "string",      "type": "steps",      "plan": "string",      "replicas": 1,      "desired_replicas": 0,      "ready_replicas": 0,      "availability": "always",      "run_state": "stopped",      "status": "pending",      "status_detail": "string",      "ports": [        {          "port": 1,          "public": true,          "url": "string",          "routes": [            {              "path": "string",              "strip": true            }          ]        }      ],      "health": {        "port": 0,        "path": "string",        "mode": "any-http"      },      "max_replicas": 1,      "image": "string",      "image_ref": "string",      "run_as_user": 0,      "autonomous": true,      "target": "string",      "routes": [        {          "path": "string",          "strip": true        }      ],      "run_result": {        "result": "success",        "generation": 0,        "message": "string",        "at": "2019-08-24T14:15:22Z"      },      "upgrade_pending": true,      "managed_service_id": "77427583-c503-4b42-8d68-8e0a3b2c8384",      "managed_status": "creating",      "needs": [        "string"      ],      "failing": true    }  ]}

Read harthelm.yml

The profile's file (`harthelm.yml`, or `harthelm.<profile>.yml`) from `/data/app`, read through the IDE agent, with its SHA-256 (also the `ETag`), the HEAD commit and the profiles that exist. 404 when the profile's file does not exist (the editor starts from a template); 409 "The workspace is not running." without an IDE pod (an asleep IDE is woken first, as for a Plan); 413 above 1 MiB; 422 when the file is not UTF-8. Needs `workspace.view`.

List the profiles

The profiles whose files exist in `/data/app`, the default (`""`, `harthelm.yml`) first, then by name; read through the IDE agent. `selected_profile` is what Plan and Sync use when the request names none, `synced_profile` what the landscape was last synced from. 409 without an IDE pod. Needs `workspace.view`.