Every resource has a name: its full path, starting with its project. Responses return only full names. Requests may write the project part shorter.
Formats
All names start with the project:
tenants/{tenant}/organizations/{organization}/projects/{project}The rest of the name depends on the resource:
| Resource | Name after the project |
|---|---|
| Sandbox | sandboxes/{sandbox} |
| Process | sandboxes/{sandbox}/processes/{process} |
| Port | sandboxes/{sandbox}/ports/{port} |
| SSH access | sandboxes/{sandbox}/sshAccess |
| Template | templates/{template} |
| Template version | templates/{template}/versions/{version} |
| Snapshot | snapshots/{snapshot} |
| Volume | volumes/{volume} |
| Operation | operations/{operation} |
| Agent | agents/{agent} |
| Agent revision | agents/{agent}/revisions/{revision} |
| Session | agents/{agent}/sessions/{session} |
| Service | services/{service} |
| Service revision | services/{service}/revisions/{revision} |
A port’s id is its port number, so port 3000 of the sandbox demo is sandboxes/demo/ports/3000. A sandbox has one SSH access resource, so its name has no id.
The SDKs take the short id where the parent is clear, as in sutra.sandboxes.get("demo") or sandbox.ports.get(3000), and return the full name in name.
Shorter forms
Your API key belongs to one organization. A request can leave out the parts of a name that the key already gives:
| Written | Means |
|---|---|
projects/{project}/sandboxes/{sandbox} |
The sandbox in a project of your organization. |
organizations/{organization}/projects/{project}/sandboxes/{sandbox} |
The sandbox in a project of that organization. |
tenants/{tenant}/organizations/{organization}/projects/{project}/sandboxes/{sandbox} |
The full name. |
A project on its own can also be written as its id, {project}. Every field that takes a name accepts these forms, and so does the path of every REST call. Two spellings of one resource are the same resource, so a request repeated under another spelling is the same request.
Ids
You choose the id when you create a resource, or leave it out and Sutra assigns one. An assigned id is a short prefix for the kind of resource, a hyphen and 12 lowercase letters and digits, such as sbx-k3f9x2m7q4h8. A create repeated with the same requestId gets the same id.
- An id is 1 to 63 characters from
A-Z,a-z,0-9,.,_,~and-. - The rule is the same for every resource.
- An id is unique among its siblings. Once the delete of a resource has completed, you can reuse its id.
Every resource also has a uid that Sutra assigns and never reuses. Use it when you need to tell apart two resources that had the same name at different times.
Host names, such as a port’s address, are never made from ids, so an id does not show up in a URL.