The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it, click on API to find the URL endpoint.
Some of the resource type names used in the API do not match the current terminology used in the UI. In particular:
| UI | API | Description |
|---|---|---|
| Environment | project | A group of physical resources, such as hosts |
In the documentation, we have used the UI term in descriptions and have provided additional disclaimers on the differences. This confusion will be cleared up in a future version of the API.
API requests must include authentication information if Access Control is enabled. Authentication is done with HTTP basic authentication using API Keys. API keys can either belong to a single (UI) Environment / (API) Project with access to just that Environment, or to a Account with access to all Environments the account belongs to, and the ability to create new ones. There is also a separate JSON Web Token interface primarily for the UI.
Note: In our examples, we’ve assumed that the
${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}are Account API Keys, but if you were to use an Environment API Key, you could omit theprojects/${PROJECT_ID}from the URL.
Environment API keys can be created in the UI, see API & Keys. The key is owned by the Environment and has full access to manage that Environment, but no access to any others. Membership roles do not apply to these keys.
Account API keys are not currently exposed in the UI. You can create one by clicking into the API in a browser:
/v2-beta/apikeysCreateaccountId that you want to create a key forname and descriptionShow Request, then Send RequestpublicValue and secretValue in the responseAccount keys can create new Environments, and have can be used to access multiple Environments via /v2-beta/projects/. Membership roles apply to these keys and restrict what Environments the account can see and what actions they can take.
/v2-beta/projects/<project_id>/<resource>/project/<project_id> part.1a5 using an Environment API key, /v2-beta/projects/1a5 is the same as /v2-beta and /v2-beta/projects/1a5/hosts is the same as /v2-beta/hosts./v2-beta/<type> version. If using an Account key, add in the path for the appropriate environment.The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, see here.
So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a X-Api-Schemas header. From there you can follow the collection link on each schema to know where to list resources, and other links inside of the returned resources to get any other information.
In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (/v2-beta/<type>) or get a specific resource (/v2-beta/<type>/<id>). Anything deeper than that is subject to change in future releases.
Resources have relationships between each other called links. Each resource includes a map of links with the name of the link and the URL to retrieve that information. Again you should GET the resource and then follow the URL in the links map, not construct these strings yourself.
Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP POST to the URL in the actions map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.
To edit a resource, send a HTTP PUT to the links.self link on the resource with the fields that you want to change. Unknown fields and ones that are not editable are ignored.
To delete a resource, send a HTTP DELETE to the links.self link on the resource. Note that some resources may need to be deactivated before they can be deleted, and deleted resources can still be retrieved from the API if you ask specifically for them by ID.
POST to the collection URL in the schema (which is /v2-beta/<type>).Most collections can be filtered on the server-side by common fields using HTTP query parameters. The filters map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple “equals” matches it’s just field=value. Modifiers can be added to the field name, e.g. field_gt=42 for “field is greater than 42”. See the API spec for full details.
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The sortLinks map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
API responses are paginated with a limit of 100 resources per page by default. This can be increased to up to 1000 with the limit=1000 query parameter. The pagination map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
Several Rancher features such as container logs, shell access, and statistics use WebSockets to stream information. To use these from the API:
ws:// or wss://) and a long token string.Authorization: Bearer <token_string>.token=<token_string> query parameter on the URL instead.