Calling an external API

Make an HTTP call to an instrument or service from a skill, authenticate with a stored secret, and keep the response with the project.

api_request

api_request(url, method="GET", *, json_body=None, params=None, headers=None, save_name=None,
            save_to_project=False, export=False, timeout=30, auth_secret=None)

Calls url and returns a result dict. It never raises: a timeout, a connection error or a non-2xx status comes back as success: False. Check the result and raise when the step should fail.

ArgumentMeaning
urlThe full request URL. Pass the address in as a skill input so the same skill can talk to different instruments.
method"GET", "POST", "PUT", ...
json_bodyA value sent as the JSON body.
paramsQuery-string parameters (dict).
headersRequest headers (dict).
timeoutSeconds before the request is abandoned.
auth_secretThe name of a secret to send as Authorization: Bearer <value>. It replaces any Authorization header in headers.
save_nameA file name (no extension) for the saved response. Without it nothing is saved.
save_to_projectDeprecated; prefer export. With save_name: write the response to data/api/<execution_id>/<save_name>.json in the project, which syncs with it.
exportWith save_name: upload the response to your lab's own storage bucket, when data export is configured on the rig.

The result:

KeyValue
successTrue when the request returned a 2xx status.
statusThe HTTP status code (None when the request failed).
dataThe parsed JSON body, or the text when the body is not JSON.
errorWhy it failed (failures only).
saved_pathWhere the response was saved (when saved).
tWhen the request started (epoch seconds).
def read_absorbance(plate_id: str = "P1", *, base_url: str):
    res = api_request(f"{base_url}/api/v1/read", method="POST", json_body={"plate": plate_id},
                      auth_secret="PLATE_READER_TOKEN", save_name=f"read_{plate_id}", export=True)
    if not res["success"]:
        raise RuntimeError(f"plate reader: {res['error']}")
    return {"success": True, "values": res["data"]}

Each call writes one line to the skill's log with the method, the URL and the status.

get_secret

get_secret(name, default=None)

Returns the value of the secret stored under name, or default when it is not set. It never raises. Use it when a token goes somewhere other than a bearer header.

Secrets in the cloud

Secrets are set on a lab machine (see Secrets). In the cloud there is no secret store: get_secret returns default, and api_request with auth_secret does not send the request and returns success: False with the reason. A skill that calls an authenticated instrument therefore needs an is_sim_mode() branch, or a check of the result, to run in the cloud simulator.

Handling credentials

  • Never write a token in skill code or pass one as a workflow input. Store it as a secret and use auth_secret or get_secret.
  • Never log, return or send a secret value.
  • Never put a token in a URL or a query string: URLs are written to the log.

Did this page help you?