API for Pooled Environments

Claiming an environment

This endpoint is used to claim a pooled GCP environment. If the response results in a 429, this means that the pool you are trying to claim from is temporarily out of environments. We're working to ensure no teams ever get this error, but our pools are finite for now.

HTTP Request

POST /pooled_gcp_engineering_environments/claim

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token. This can be obtained from CF Toolsmiths via slack/email
pool_name	Yes	The name of the pool which you wish to claim an environment from. You can see the different pools here: https://environments.toolsmiths.cf-app.com/pooled_gcp_environments
notes	No	Notes you wish to leave on the environment. The notes are displayed when the /list endpoint is envoked

Example Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl -X POST "https://environments.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/claim?api_token=$TOOLSMITHS_API_TOKEN&pool_name=us_1_12&notes=claimed%20by%20mikejarvis" | jq .

Example Response

The response is the metadata file for the deployment_type of your environment. The schema can be found here.

Renewing an environment

This endpoint is used to renew a pooled GCP environment so that it can be used for up to 7 days. Using this endpoint changes the self_destruct_timestamp so that it is 7 days from when you claimed the environment. This endpoint can really only be used 1x per environment.

HTTP Request

POST /pooled_gcp_engineering_environments/renew

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token
name	Yes	The name of the environment which you wish to renew

Example Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl -v -X POST "https://environments.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/renew?api_token=$TOOLSMITHS_API_TOKEN&name=denim"

Example Response

{
"message": "Thank you! Environment 'denim' has been renewed.",
"self_destruct_timestamp": "2018-01-07T01:01:00.000Z"
}

Unclaiming an environment

This endpoint is used to unclaim a pooled GCP environment.

HTTP Request

POST /pooled_gcp_engineering_environments/unclaim

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token
name	Yes	The name of the environment which you wish to unclaim

Example Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl -v -X POST "https://environments.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/unclaim?api_token=$TOOLSMITHS_API_TOKEN&name=denim"

Example Response

HTTP/1.1 202 ACCEPTED

List claimed environments

This endpoint is used to list all claimed pooled GCP environments for a particular team.

HTTP Request

GET /pooled_gcp_engineering_environments/list

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token

Example Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/list?api_token=$TOOLSMITHS_API_TOKEN" | jq .

Example Response

[
  {
    "name": "denim",
    "pool_name": "us_2_3",
    "last_claimed_at": "2019-11-06T20:16:40.000Z",
    "claim_duration_hours": 24,
    "opsman_version": "2.3-build.354",
    "ert_version": "2.3.18-build.8",
    "notes": "testing_auto_delete",
    "unclaim_url": "https://environments-staging.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/unclaim?api_token=<redacted>&name=denim-staging",
    "credentials_url": "https://environments-staging.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/claim?api_token=9ecaf75a-6cb0-439b-b375-37db943eda51&environment_name=denim-staging",
    "self_destruct_timestamp": "2019-11-07T20:16:40.000Z"
  },
  {
    "name": "navy",
    "pool_name": "us_2_3",
    "last_claimed_at": "2019-11-06T20:16:40.000Z",
    "claim_duration_hours": 24,
    "opsman_version": "2.3-build.354",
    "ert_version": "2.3.18-build.8",
    "notes": "testing_auto_renew",
    "unclaim_url": "https://environments-staging.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/unclaim?api_token=<redacted>&name=denim-staging",
    "credentials_url": "https://environments-staging.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/claim?api_token=9ecaf75a-6cb0-439b-b375-37db943eda51&environment_name=denim-staging",
    "self_destruct_timestamp": "2019-11-07T22:16:40.000Z"
  }
]

Fetching the metadata file for an environment

This endpoint is used to fetch the metadata file for an environment. The metadata file contains detailed information about an environment.

HTTP Request

GET /pooled_gcp_engineering_environments/claim

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token
environment_name	Yes	The environment name

Example Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/pooled_gcp_engineering_environments/claim?api_token=$TOOLSMITHS_API_TOKEN&environment_name=blue" | jq .

Example Response

The response is the metadata file for the deployment_type of your environment. The schema can be found here.

Fetching the list of available pools

This endpoint is used to fetch the list of available pools.

WARNING: The presence of a pool name in this list does not indicate whether or not the pool is currently empty. You may still get 429s when requesting an environment from a pool in this list.

HTTP Request

GET /pool_names

Query Parameters

No query parameters required

Example Request

curl "https://environments.toolsmiths.cf-app.com/pool_names"

Example Response

HTTP/1.1 200 OK

{
  "pool_names": {
   "gcp": [
    "us_1_12_srt",
    "us_2_1_srt",
    "us_2_1"
   ]
  }
}