OverviewThis page serves as an overview of the Chef Server REST API, and on managing API clients through this Server API.API Clients can also be managed via Knife or the Open Source Chef Server Management Console, see API Clients for documentation on those approaches, and [LEG:Authentication] for the process of authentication and validation of the clients access to the server. There are requirements in order to interact with the Chef Server REST API. In order to make any of these API calls, you will need to satisfy these pre-requisites:
The easiest way to ensure a well formatted request is to use the Chef::REST library bundled with Chef. See the [LEG:Authentication] page for more information about Chef's authentication mechanism. /clientsManipulate or create API Clients. HTTP MethodsGETReturns a list of all the API clients. This includes the API Client registration for each Chef node, any other API users you may create, and the validation and webui clients. ResponseResponse to a GET on /clients
|
|
POSTCreates a new client. The body for a POST to /clients The name field should be the name of the client you want created. The admin field controls whether or not this is an "admin" client (meaning it can manipulate most objects in the system.) ResponseThe response to a POST to /clients You will want to make sure you store the contents of the private_key attribute after creation. You can then use this client name and private key to access the REST API.
/clients/CLIENT_NAMEHTTP MethodsGETReturns the client. ResponseThe response to a GET of /clients/CLIENT_NAME
PUTUpdates the client. The request body should be: The response to a PUT to /clients/CLIENT_NAME If private_key is set to true, a new key-pair for this client will be generated, and the new private key will be returned in the response body. If admin is set, this client will be promoted to an administrator. ResponseThe response to a PUT to /clients/CLIENT_NAME
DELETERemoves the client. Request has no body. Response
In order to minimize storage and the amount of time required to iterate in the modify-upload-test cycle, cookbooks only require that files with checksums the system has not yet seen be uploaded. To accomplish this, a cookbook version's component files (each with its own particular checksum) are uploaded using the sandbox API. These checksums are then used in the version's manifest in records that include the component file's description (name, specificity, etc.), as well as its checksum and a URL from which to retrieve the file's contents. This is why you will see only the files that you have updated get uploaded when doing a "knife cookbook upload COOKBOOK_NAME". /cookbooksHTTP MethodsGETChef 0.9.x:Returns a list of all the cookbooks on this chef server. The request has no body, and returns a hash as follows: ResponseResponse to GET /cookbooks Chef 0.10.0 or above:Returns a hash of all the cookbooks and their versions. Query parameter num_versions can be used to set the number of versions being returned. For example, GET to /cookbooks?num_versions=3 returns 3 latest versions, in descending order (high to low); /cookbooks?num_versions=all returns all available versions, in descending order (high to low). If num_versions is not specified, it defaults to 1. Note that 0 is a valid input that returns an empty array for the versions of each cookbooks. The request has no body, and returns a hash as follows: ResponseExample response to GET /cookbooks?num_versions=all
/cookbooks/COOKBOOK_NAMEHTTP MethodsGETChef 0.9.xReturns a listing of the versions of the cookbook. ResponseResponse to GET /cookbooks/unicorn Chef 0.10.0 and aboveReturns a hash in the same format as the /cookbooks API endpoint. The hash contains one key-value pair corresponding to the cookbook requested. The same query parameters as the /cookbooks endpoint apply. The num_versions query parameter defaults to "all". Response to GET /cookbooks
/cookbooks/COOKBOOK_NAME/COOKBOOK_VERSIONHTTP MethodsGETReturns a description of the cookbook, including its metadata and links to all of its component files. COOKBOOK_VERSION can be "_latest" in order to float to head. It requires no request body. ResponseResponse to GET /cookbooks/unicorn/0.1.0
PUTCreates or updates the cookbook version. The payload is the cookbook version's manifest, which is identical to the response of a cookbook version GET except without the URL fields for each component. Note that all checksums must have been uploaded by the user at some point via the sandbox mechanism; however, once a file with a particular checksum has been uploaded by the user, redundant uploads are not necessary. Response
DELETEDeletes a cookbook version. Response
Data BagsData Bags allow you to store arbitrary data about your infrastructure. /dataData Bags can be used for all sorts of things, for example, application configuration and user data, etc. HTTP MethodsGETReturns a list of all the data bags. ResponseResponse to GET /data The key is the name of the data bag, and the value is the URI for that data bag.
POSTCreates a new data bag. Request body for a POST to /data ResponseResponse to a POST on /data
/data/DATA_BAG_NAMEHTTP MethodsGETReturns a hash of all the entries in the given bag. ResponseResponse to a GET on /data/DATA_BAG_NAME
POSTCreates a new data bag item. The request must contain an "id" field: Request body for a POST to /data/DATA_BAG_NAME Response
/data/DATA_BAG_NAME/DATA_BAG_ITEM_IDThis endpoint allows you to show/manipulate data bag items within a bag. The data bag item itself can be any arbitrary JSON you construct. HTTP MethodsGETReturns the data bag item in the bag. ResponseResponse to a GET on /data/DATA_BAG_NAME/DATA_BAG_ITEM_ID
PUTUpdates the data bag item in the bag. The request body must contain an "id" field, besides that, you can use any JSON you wish. Request body for a PUT to /data/DATA_BAG_NAME/DATA_BAG_ITEM_ID ResponseThe response body will be the current value of the item - which should be identical to your request.
DELETERemoves a data bag item from the bag. Takes no request body, and returns the last state of the item in the response. ResponseResponse to a DELETE on /data/DATA_BAG_NAME/DATA_BAG_ITEM_ID
NodesNodes are systems that run the chef client. /nodesHTTP MethodsGETReturns a hash of uri's for the nodes. Response CodesResponse to GET /nodes The key is the name of the node, and the value is the URI where it can be retrieved.
POSTA POST request to /nodes will create a new node. A sample request body: Request body for a POST to /nodes The name should be the name of the node you want created. The attributes hash should contain any attributes you want set for this node - overrides and defaults correspond to override and default attributes. The run_list should be an array containing recipes and roles. Note that order matters in the run_list array. ResponseIn response you should receive: Response to a POST on /nodes
/nodes/NODE_NAMEGETA GET request to /nodes/NODE will return the node. ResponseResponse to a GET /nodes/NODE
PUTA PUT request to /nodes/NODE will update the node. The request body should be the Node: Request body for a PUT to /nodes/NODE ResponseThe response will be the updated node.
DELETEA DELETE request to /nodes/NODE will delete the node. It requires no request body, and returns the last known state of the node. Request body for a DELETE to /nodes/NODE Response Codes
/nodes/NODE_NAME/cookbooksHTTP MethodsGETReturns the complete list of cookbook attributes, definitions, libraries and recipes that are required for this node. The request body should be blank, and the response will look like: ResponseResponse to a /nodes/NODE/cookbooks request
/rolesHTTP MethodsGETA GET call to /roles returns a data structure that contains links to each available role. ResponseResponse to GET /roles
POSTA POST call to /roles creates a new role. The request body should contain the JSON representation of the role. Request body for a POST to /roles ResponseIn response, you will receive: Response to a POST on /roles
/roles/ROLE_NAMEHTTP MethodsGETA GET to /roles/ROLE returns the JSON representation of the role. ResponseResponse to GET /roles/ROLE
PUTA PUT to /roles/ROLE updates the Role. Request body for a PUT to /roles/ROLE ResponseThe response will be the updated role.
DELETEA DELETE to /roles/ROLE_NAME deletes the role. This request has no body. ResponseThe response to a DELETE request is the role's state just before it was removed. Response to DELETE /roles/ROLE_NAME
/environmentsHTTP MethodsGETA GET call to /environments returns a data structure that contains links to each available environment. ResponseResponse to GET /environments
POSTA POST call to /environments creates a new environment. The request body should contain the JSON representation of the environment. Request body for a POST to /environments ResponseIn response, you will receive: Response to a POST on /environments
/environments/ENVIRONMENT_NAMEHTTP MethodsGETA GET to /environments/ENVIRONMENT returns the JSON representation of the environment. ResponseResponse to GET /environments/ENVIRONMENT
PUTA PUT to /environments/ENVIRONMENT updates the Environment. Request body for a PUT to /environments/ENVIRONMENT ResponseThe response will be the updated environment.
DELETEA DELETE to /environments/ENVIRONMENT_NAME deletes the environment. This request has no body. ResponseThe response to a DELETE request is the environment's state just before it was removed. Response to DELETE /environments/ENVIRONMENT_NAME
/environments/:environment_id/cookbooksHTTP MethodsGETReturns a list of all the cookbooks and their versions that are available to the specified Environment. Query parameter num_versions can be used to set the number of versions being returned. For example, GET to /environment/production/cookbooks?num_versions=3 returns 3 latest versions, in descending order (high to low); /environments/production/cookbooks?num_versions=all returns all available versions in this environment, in descending order (high to low). If num_versions is not specified, it defaults to 1. Note that 0 is a valid input that returns an empty array for the versions of each cookbooks. The request has no body, and returns a hash as follows: ResponseResponse to GET /cookbooks
/environments/:environment_id/cookbook_versionsHTTP MethodsPOSTReturns a hash of the required versions of cookbooks and their dependencies for the given run_list array. Version constraints may be specified by using the '@' symbol after the cookbook name as a delimiter. /environments/:environment_id/cookbooks/COOKBOOK_NAMEHTTP MethodsGETReturns a hash in the same format as the /environments/:env_id/cookbooks API endpoint. The hash contains one key-value pair corresponding to the cookbook requested. The versions displayed are filtered based on the environment specified. The same query parameters as the /environments/:env_id/cookbooks endpoint apply. The num_versions query parameter defaults to "all". Response to GET /cookbooks
/searchThis endpoint allows you to search your entire organizations nodes, roles, and data bags. HTTP MethodsGETA GET call to /search returns a data structure that contains links to each available search index. By default, the "role", "node" and "client" indexes will always be available. Note that the search indexes may lag behind the most current data by at least 10 seconds at any given time. If you need to write data and immediately query it, you likely need to produce an artificial delay (or simply retry until the data is available.) ResponseResponse to GET /search
/search/INDEXHTTP MethodsGETA GET call to /search/INDEX without any request parameters will return all of the data within the index. ResponseResponse to GET /search/node The response contains the total number of rows that matched your request, the position this result set returns (useful for paging) and the rows themselves. You can modify the search results with the following request parameters:
See the Search Query Syntax for help on composing search strings.
/sandboxesCreate or list sandboxes. HTTP MethodsPOSTCreates a new sandbox. It accepts a list of checksums as input and returns the URLs against which to PUT files that need to be uploaded. RequestRequest body for a POST to /sandboxes ResponseResponse to a POST to /sandboxes
/sandboxes/SANDBOX_IDHTTP MethodsPUTCommits the files the sandbox to their final location so that proceeding cookbook changes will not require re-uploading the same data. RequestRequest body for a PUT to /sandboxes/SANDBOX_ID Response
/sandboxes/SANDBOX_ID/CHECKSUMHTTP MethodsPUTRequestThe contents of the file whose checksum is CHECKSUM.
Response
pychefOpscode Team Member Noah Kantrowitz (coderanger) has written PyChef, a Python API allowing interaction with the Chef REST interface. While only a subset of Chef is currently wrapped as objects, any of the API calls below can be made via the api_request mechanism:
|
|
|
|
1 Comment
comments.show.hideJul 21, 2010
Pascal Rettig
Doesn't seem like setting "attributes" on a put does anything in the current version of Chef - setting
"normal" seems to set the node attributes though, e.g.:
{
"name": "latte",
"chef_type": "node",
"json_class": "Chef::Node",
"normal": {
"hardware_type": "laptop"
},
"overrides": {
},
"defaults": {
},
"run_list": [ "recipe[unicorn]" ]
}
Actually results in the hardware_type getting permanently added to the node's attributes.