Chef

Table Of Contents

Chef Server API

The Chef server API is a REST API that provides access to objects on the Chef server, including nodes, environments, roles, cookbooks (and cookbook versions), and to manage an API client list and the associated RSA public key-pairs.

Requirements

The Chef server API has the following requirements:

  • Access to a Chef server running version 0.10.x or above
  • The Accept header must be set to application/json
  • For PUT and POST requests, the Content-Type header must be set to application/json
  • The X-Chef-Version header must be set to the version of the Chef server API that is being used
  • A request must be signed using Mixlib::Authentication
  • A request must be well-formatted. The easiest way to ensure a well-formatted request is to use the Chef::REST library

Authentication Headers

Authentication to the Chef server occurs when a specific set of HTTP headers are signed using a private key that is associated with the machine from which the request is made. The request is authorized if the Chef server can verify the signature using the public key. Only authorized actions are allowed.

Note

Most authentication requests made to the Chef server are abstracted from the user. Such as when using knife or the Chef server user interface. In some cases, such as when using the knife exec subcommand, the authentication requests need to be made more explicitly, but still in a way that does not require authentication headers. In a few cases, such as when using arbitrary Ruby code or cURL, it may be necessary to include the full authentication header as part of the request to the Chef server.

Header Format

All hashing is done using SHA1 and encoded in Base64. Base64 encoding should have line breaks every 60 characters. Each canonical header should be encoded in the following format:

Method:HTTP_METHOD
Hashed Path:HASHED_PATH
X-Ops-Content-Hash:HASHED_BODY
X-Ops-Timestamp:TIME
X-Ops-UserId:USERID

where:

  • HTTP_METHOD is the method used in the API request (GET, POST, and so on)
  • HASHED_PATH is the path of the request: /organizations/organization_name/name_of_endpoint. The HASHED_PATH must be hashed using SHA1 and encoded using Base64, must not have repeated forward slashes (/), must not end in a forward slash (unless the path is /), and must not include a query string.
  • The private key must be an RSA key in the SSL .pem file format. This signature is then broken into character strings (of not more than 60 characters per line) and placed in the header.

The Chef server decrypts this header and ensures its content matches the content of the non-encrypted headers that were in the request. The timestamp of the message is checked to ensure the request was received within a reasonable amount of time. One approach generating the signed headers is to use mixlib-authentication, which is a class-based header signing authentication object similar to the one used by the chef-client.

Required Headers

The following authentication headers are required:

Feature Description
Accept The format in which response data from the Chef server is provided. This header must be set to application/json.
Content-Type The format in which data is sent to the Chef server. This header is required for PUT and POST requests and must be set to application/json.
Host The host name (and port number) to which a request is sent. (Port number 80 does not need to be specified.) For example: api.opscode.com (which is the same as api.opscode.com:80) or api.opscode.com:443.
X-Chef-Version The version of the chef-client executable from which a request is made. This header ensures that responses are in the correct format. For example: 11.0.4.x or 0.10.x.
X-Ops-Authorization-N One (or more) 60 character segments that comprise the canonical header. A canonical header is signed with the private key used by the client machine from which the request is sent, and is also encoded using Base64. If more than one segment is required, each should be named sequentially, e.g. X-Ops-Authorization-1, X-Ops-Authorization-2, X-Ops-Authorization-N, where N represents the integer used by the last header that is part of the request.
X-Ops-Content-Hash The body of the request. The body should be hashed using SHA1 and encoded using Base64. All hashing is done using SHA1 and encoded in Base64. Base64 encoding should have line breaks every 60 characters.
X-Ops-Sign Set this header to the following value: version=1.0.
X-Ops-Timestamp The timestamp, in ISO-8601 format and with UTC indicated by a trailing Z and separated by the character T. For example: 2013-03-10T14:14:44Z.
X-Ops-UserId The name of the API client whose private key will be used to create the authorization header.

Example

The following example shows an authentication request:

GET /organizations/organization_name/nodes HTTP/1.1
  Accept: application/json
  Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
  X-Ops-Sign: algorithm=sha1;version=1.0;
  X-Ops-Userid: user_id
  X-Ops-Timestamp: 2013-03-12T17:13:28Z
  X-Ops-Content-Hash: 2jmj7l5rfasfgSw0ygaVb/vlWAghYkK/YBwk=
  X-Ops-Authorization-1: BE3NnHeh5yFTiT3ifuwLSPCCYasdfXaRN5oZb4c6hbW0aefI
  X-Ops-Authorization-2: sL4j1qtEZzi/2WeF67UuytdsdfgbOc5CjgECQwqrym9gCUON
  X-Ops-Authorization-3: yf0p7PrLRCNasdfaHhQ2LWoE/+kTcu0dkasdfvaTghfCDC57
  X-Ops-Authorization-4: 155i+ZlthfasfhbfrtukusbIUGBKUYFjhbvcds3k0i0gqs+V
  X-Ops-Authorization-5: /sLcR7JjQky7sdafIHNEEBQrISktNCDGfFI9o6hbFIayFBx3
  X-Ops-Authorization-6: nodilAGMb166@haC/fttwlWQ2N1LasdqqGomRedtyhSqXA==
  Host: api.opscode.com:443
  X-Chef-Version: 11.4.0
  User-Agent: Chef Knife/11.4.0 (ruby-1.9.2-p320; ohai-6.16.0; x86_64-darwin11.3.0; +http://opscode.com)

Global Endpoints

A global endpoint may be used to access all of the organizations on the Chef server.

/organizations

The Chef server may contain multiple organizations.

The /organizations endpoint has the following methods: GET and POST.

GET

The GET method is used to get a list of organizations on the Chef server.

This method has no parameters.

Request

GET /organizations/ORG_NAME/organizations

Response

The response will return something like the following:

{
  "org_name1"=>"https://url/for/org_name1"
  "org_name2"=>"https://url/for/org_name2"
      ...
}

Response Codes

Response Code Description
200 OK. The request was successful.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create an organization on the Chef server.

This method has no parameters.

Request

POST /organizations

with a request body that looks something like:

{
  "name": "chef",
  "full_name": "Chef Software, Inc.",
}

where:

  • name must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores, and must be between 1 and 255 characters. For example: chef.
  • full_name must begin with a non-white space character and must be between 1 and 1023 characters. For example: Chef Software, Inc..

Note

An organization isn’t usable until a user that belongs to the admins group is associated with the organization.

Response

The response will return something like the following:

{ "org_name"=>"https://url/for/org_name" }

Response Codes

Response Code Description
200 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Unauthorized. The user which made the request is not authorized to perform the action.

/organizations/NAME

An organization is a single instance of a Chef server, including all of the nodes that are managed by that Chef server and each of the workstations that will run knife and access the Chef server using the Chef server API.

The /organizations/NAME endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete an organization.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME

Response

The response will return something like the following:

{
  "name"=>"chef",
  "full_name"=>"Chef Software, Inc",
  "guid"=>"f980d1asdfda0331235s00ff36862
}

Response Codes

Response Code Description
200 OK. The request was successful.
403 Forbidden. The user which made the request is not authorized to perform the action.

GET

The GET method is used to get the details for the named organization.

This method has no parameters.

Request

GET /organizations/NAME

Response

The response will return something like the following:

{
  "name"=>"chef",
  "full_name"=>"Chef Software, Inc",
  "guid"=>"f980d1asdfda0331235s00ff36862
      ...
}

Response Codes

Response Code Description
200 OK. The request was successful.
403 Forbidden. The user which made the request is not authorized to perform the action.

PUT

The PUT method is used to create an organization.

This method has no parameters.

Request

PUT /organizations/ORG_NAME

with a request body that looks something like:

{
  "name": "chef",
  "full_name"=>"Chef Software, Inc",
}

Response

The response will return the JSON for the updated organization.

Response Codes

Response Code Description
200 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
403 Forbidden. The user which made the request is not authorized to perform the action.
410 Gone. Unable to update private key.

/users

A user is an individual account that is created to allow access to the Chef server. For example:

  • A hosted Chef server account
  • The user who operates the workstation from which a Chef server will be managed

The /users endpoint has the following methods: `GET and POST.

GET

The GET method is used to get a list of users on the Chef server.

This method has no parameters.

Request

GET /users

Response

The response will return something like the following:

{
  "user1"=>"https://url/for/user1"
  "user2"=>"https://url/for/user2"
      ...
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

POST

The POST method is used to create a user on the Chef server.

This method has no parameters.

Request

POST /users

Response

The response will return something like the following:

{ "user_name"=>"https://url/for/user_name" }

Response Codes

Response Code Description
200 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/users/NAME

The /users/USER_NAME endpoint has the following methods: DELETE, GET, POST, and PUT.

DELETE

The DELETE method is used to delete a user.

This method has no parameters.

Request

DELETE /users/USER_NAME

Response

The response will return something similar to:

{
  "name": "Grant McLennan",
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to return the details for a user.

This method has no parameters.

Request

GET /users/USER_NAME

Response

The response will return something like the following:

{
  "name": "Robert Forster",
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create a new user. If a public key is not specified, both public and private keys will be generated and returned. If a public key is specified, only the public key will be returned.

This method has no parameters.

Request

POST /users/USER_NAME

with a request body that looks something like:

{
  "name": "Robert Forster"
}

Response

The response will return something like the following:

{
  "name": "Robert Forster",
  "private_key": "-----BEGIN PRIVATE KEY-----\n
                MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyVPW9YXa5PR0rgEW1updSxygB\n
                wmVpDnHurgQ7/gbh+PmY49EZsfrZSbKgSKy+rxdsVoSoU+krYtHvYIwVfr2tk0FP\n
                nhAWJaFH654KpuCNG6x6iMLtzGO1Ma/VzHnFqoOeSCKHXDhmHwJAjGDTPAgCJQiI\n
                eau6cDNJRiJ7j0/xBwIDAQAB\n
                -----END PRIVATE KEY-----"
  "admin": true
}

Response Codes

Response Code Description
201 Created. The object was created.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

PUT

The PUT method is used to update a specific user. If values are not specified for the PUT method, the Chef server will use the existing values rather than assign default values.

PUT accepts a boolean: { "private_key": "true" }. If this is specified, a new private key is generated.

If values are missing, they will not be overwritten. If public_key is null, the public key will not be overwritten.

Note

PUT supports renames. If PUT /users/foo is requested with { "name: "bar""}, then it will rename foo to bar and all of the content previously associated with foo will be associated with bar.

This method has no parameters.

Request

PUT /users/NAME

with a request body that looks something like:

POST /users { "name": "Grant McLennan" }

Response

The response will return something like the following:

{
  "name": "Grant McLennan",
  "private_key": "-----BEGIN PRIVATE KEY-----\n
                MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyVPW9YXa5PR0rgEW1updSxygB\n
                wmVpDnHurgQ7/gbh+PmY49EZsfrZSbKgSKy+rxdsVoSoU+krYtHvYIwVfr2tk0FP\n
                nhAWJaFH654KpuCNG6x6iMLtzGO1Ma/VzHnFqoOeSCKHXDhmHwJAjGDTPAgCJQiI\n
                eau6cDNJRiJ7j0/xBwIDAQAB\n
                -----END PRIVATE KEY-----"
  "admin": false
}

If a new private key was generated, both the private and public keys are returned.

Response Codes

Response Code Description
200 OK. The request was successful.
201 Created. The object was created. (This response code is only returned when the user is renamed.)
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
409 Unauthorized. The user which made the request is not authorized to perform the action. (This response code is only returned when a user is renamed, but a user already exists with that name.)
413 Request entity too large. A request may not be larger than 1000000 bytes.

Organization Endpoints

Each organization-specific authentication request must include /organizations/ORG_NAME as part of the name for the endpoint. For example, the full endpoint for getting a list of roles:

GET /organizations/ORG_NAME/roles

where ORG_NAME is the name of the organization.

/clients

The /clients endpoint is used to manage an API client list and their associated RSA public key-pairs.

Note

In general, the API client list should be managed using knife or the Chef server management console, as opposed to the Chef server API.

The /clients endpoint has the following methods: GET and POST.

GET

The GET method is used to return the API client list on the Chef server, including nodes that have been registered with the Chef server, the chef-validator clients, and the chef-server-webui clients.

This method has no parameters.

Request

GET /organizations/ORG_NAME/clients

Response

The response will return something like the following:

{
  "client1": "https://api.opscode.com/organizations/org_name/clients/client_name",
  "client2": "https://api.opscode.com/organizations/org_name/clients/client_name"
}

or:

{
  "client1": "http://localhost:4000/clients/client_name",
  "client2": "http://localhost:4000/clients/client_name",
  "client3": "http://localhost:4000/clients/client_name"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create a new API client.

This method has no parameters.

Request

POST /organizations/ORG_NAME/clients

with a request body that looks something like:

{
  "name": "name_of_API_client",
  "admin": false
}

where name_of_API_client is the name of the API client to be created and admin indicates whether the API client will be run as an admin API client.

Response

The response will return something like the following:

{
  "uri": "http://localhost:4000/clients/monkeypants",
  "private_key": "-----BEGIN PRIVATE KEY-----\n
                MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyVPW9YXa5PR0rgEW1updSxygB\n
                wmVpDnHurgQ7/gbh+PmY49EZsfrZSbKgSKy+rxdsVoSoU+krYtHvYIwVfr2tk0FP\n
                nhAWJaFH654KpuCNG6x6iMLtzGO1Ma/VzHnFqoOeSCKHXDhmHwJAjGDTPAgCJQiI\n
                eau6cDNJRiJ7j0/xBwIDAQAB\n
                -----END PRIVATE KEY-----"
}

Store the private key in a safe place. It will be required later (along with the client name) to access the Chef server when using the Chef server API.

Response Codes

Response Code Description
201 Created. The object was created.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/clients/NAME

The /clients/NAME endpoint is used to manage a specific API client. This endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to remove a specific API client.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME/clients/NAME

This method has no request body.

Response

This method has no response body.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to return a specific API client.

This method has no parameters.

Request

GET /organizations/ORG_NAME/clients/NAME

Response

The response will return something like the following:

{
  "clientname": "client_name",
  "orgname": "org_name",
  "validator": false,
  "certificate": "-----BEGIN CERTIFICATE-----\n
                  MIIDOjCCAqOgAwIBAgIE47eOmDANBgkqhkiG9w0BAQUFADCBnjELMAkGA1UEBhMC\n
                  VVMxEzARBgNVBAgMCldhc2hpbmd0b24xfrsgbg@VBAcMB1NlYXR0bGUxFjAUBgNV\n
                  BAoMDU9wc2NvZGUsIEluYy4xHDAaBgNVBAsME0NlcnRpZmljYXRlIFNlcnZpY2Ux\n
                  MjAwBgNVBAMMKW9wc2NvZGUuY29tL2VtYWlsQWRkcmVzcz1hdXRoQG9wc2NvZGUu\n
                  Y29tMCAXDTEyMDkwNzE4MDUwOFo1234g5ghdcDAzMTgwNTA4WjCBnTEQMA4GA1UE\n
                  BxMHU2VhdHRsZTETMBEGA1UECBMKV2FzaGluZ3RvbjELMAkGA1UEBhMCVVMxHDAa\n
                  BgNVBAsTE0NlcnRpZmljYXRlIFNlcnZpY2UxFjAUBgNVBAoTDU9wc2NvZGUsIElu\n
                  Yy4xMTAvBgNVBAMUKFVSSTpodHRwOi8vb3BzY29kZS5jb20vR1VJRFMvY2xpZW50\n
                  X2d1aWQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDJhwXHuq96iHpv\n
                  SDkDdpSAWa3O81o1ZkG1/H1GmRKc3NDp9KfL/eg/itJeVT5BJ2DXenhbP0M8BHQG\n
                  arObwx6vXm+H/Q2sdfbbhdFt5y6wQZI4Dqnv7Hk/H95jUb+MJoXpJkB7zYSqrrei\n
                  LBjjPg2p+M9+EUklelLeXDJDdj1xL5RNdDfv3yxyESTdYYVboQwgqbP3yGy7ITQc\n
                  vg11qmDzg7L17q6uQevVap6aECuGS7//CcDcKJwuBYQukJi7QFs5V4ayq6GlgfT/h\n
                  b/yjEAcfcqvBBDOO8K34fExnWTO7fdghh4btddPayHbud8dW0m3KdzhUaIh9BlGz\n
                  xFTdI8/lAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAZlvDZWmw0u0VS4mapSxuKPAz\n
                  4qhB8yttbZj8H9hUNfMdHMpyE3jJGFcLokRXdfxOsFNoPUj0hn+5BKTqtmdd6T1u\n
                  iDVoFfJ3nVPfGJMdPXZyi62pNCwPe/va13dLqTG92AGNDjjOxmMma9/OQ8Ty0eBu\n
                  HWOxaK6VpV8pqZPq/Fg=\n-----END CERTIFICATE-----\n",
  "name": "node_name"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

PUT

The PUT method is used to update a specific API client. If values are not specified for the PUT method, the Chef server will use the existing values rather than assign default values.

Note

PUT supports renames. If PUT /user/foo is requested with { "name: "bar""}, then it will rename foo to bar and all of the content previously associated with foo will be associated with bar.

This method has no parameters.

Request

PUT /organizations/ORG_NAME/clients/NAME

with a request body that looks something like:

{
  "name": "monkeypants",
  "private_key": true,
  "admin": false
}

where private_key (when true) will generate a new RSA private key for the API client. If admin is set to true the API client will be promoted to an admin API client.

Response

The response will return something like the following:

{
  "name": "monkeypants",
  "private_key": "-----BEGIN PRIVATE KEY-----\n
                MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyVPW9YXa5PR0rgEW1updSxygB\n
                wmVpDnHurgQ7/gbh+PmY49EZsfrZSbKgSKy+rxdsVoSoU+krYtHvYIwVfr2tk0FP\n
                nhAWJaFH654KpuCNG6x6iMLtzGO1Ma/VzHnFqoOeSCKHXDhmHwJAjGDTPAgCJQiI\n
                eau6cDNJRiJ7j0/xBwIDAQAB\n
                -----END PRIVATE KEY-----"
  "admin": true
}

Response Codes

Response Code Description
200 OK. The request was successful.
201 Created. The object was created. (This response code is only returned when the client is renamed.)
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
409 Unauthorized. The user which made the request is not authorized to perform the action. (This response code is only returned when a client is renamed, but a client already exists with that name.)
413 Request entity too large. A request may not be larger than 1000000 bytes.

/cookbooks

A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including:

  • Attribute values that are set on nodes
  • Definitions that allow the creation of reusable collections of resources
  • File distributions
  • Libraries that extend the chef-client and/or provide helpers to Ruby code
  • Recipes that specify which resources to manage and the order in which those resources will be applied
  • Custom resources and providers
  • Templates
  • Versions
  • Metadata about recipes (including dependencies), version constraints, supported platforms, and so on

When a cookbook is uploaded, only files that are new or updated will be included. This approach minimizes the amount of storage and time that is required during the modify-upload-test cycle. To keep track of which files have already been uploaded, the chef-client uses a checksum and assigns a checksum to each file. These checksums are used in the cookbook version manifest, alongside the same records that store the file description (name, specificity, and so on), as well as the checksum and the URL from which the file’s contents can be retrieved.

The /cookbooks endpoint has the following methods: GET.

GET

The GET method is used to return a hash of all cookbooks and cookbook versions.

This method has the following parameters:

Parameter Description
num_versions=n The number of cookbook versions to include in the response, where n is the number of cookbook versions. For example: num_versions=3 will return the three latest versions, in descending order (newest to oldest). Use num_versions=all to return all cookbook versions. If num_versions is not specified, it will return a single cookbook version. 0 is an invalid input (it will return an empty array for the versions of each cookbook).

Request

GET /organizations/ORG_NAME/cookbooks

Response

The response will return something like the following:

{
  "apache2" => {
    "url" => "http://localhost:4000/cookbooks/apache2",
    "versions" => [
      {"url" => "http://localhost:4000/cookbooks/apache2/5.1.0",
       "version" => "5.1.0"},
      {"url" => "http://localhost:4000/cookbooks/apache2/4.2.0",
       "version" => "4.2.0"}
    ]
  },
  "nginx" => {
    "url" => "http://localhost:4000/cookbooks/nginx",
    "versions" => [
      {"url" => "http://localhost:4000/cookbooks/nginx/1.0.0",
       "version" => "1.0.0"},
      {"url" => "http://localhost:4000/cookbooks/nginx/0.3.0",
       "version" => "0.3.0"}
    ]
  }
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

/cookbooks/NAME

The /cookbooks/NAME endpoint has the following methods: GET.

GET

The GET method is used to return a hash that contains a key-value pair that corresponds to the specified cookbook, with a URL for the cookbook and for each version of the cookbook.

This method has the following parameters:

Parameter Description
num_versions=n The number of cookbook versions to include in the response, where n is the number of cookbook versions. For example: num_versions=3 will return the three latest versions, in descending order (newest to oldest). Use num_versions=all to return all cookbook versions. If num_versions is not specified, it will return a single cookbook version. 0 is an invalid input (it will return an empty array for the versions of each cookbook).

Request

GET /organizations/ORG_NAME/cookbooks/NAME

Response

The response will return something like the following:

{
  "apache2" => {
    "url" => "http://localhost:4000/cookbooks/apache2",
    "versions" => [
      {"url" => "http://localhost:4000/cookbooks/apache2/5.1.0",
       "version" => "5.1.0"},
      {"url" => "http://localhost:4000/cookbooks/apache2/4.2.0",
       "version" => "4.2.0"}
    ]
  }
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/cookbooks/NAME/version

A cookbook version represents a set of functionality that is different from the cookbook on which it is based. A version may exist for many reasons, such as ensuring the correct use of a third-party component, updating a bug fix, or adding an improvement. A cookbook version is defined using syntax and operators, may be associated with environments, cookbook metadata, and/or run-lists, and may be frozen (to prevent unwanted updates from being made).

A cookbook version is maintained just like a cookbook, with regard to source control, uploading it to the Chef server, and how the chef-client applies that cookbook when configuring nodes.

The /cookbooks/NAME/VERSION endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete a cookbook version.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME/cookbooks/NAME/VERSION

Response

This method has no response body. Unused checksum values will be garbage collected.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to return a description of a cookbook, including its metadata and links to component files.

This method has no parameters.

Request

GET /organizations/ORG_NAME/cookbooks/NAME/VERSION

where VERSION can be _latest in order to float to head.

Response

The response will return something like the following:

{
  "cookbook_name": "getting-started",
  "files": [

  ],
  "chef_type": "cookbook_version",
  "definitions": [

  ],
  "libraries": [

  ],
  "attributes": [
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": "attributes/default.rb",
      "specificity": "default",
      "name": "default.rb",
      "checksum": "fa0fc4abf3f6787fdsaasadfrc5c35de667c"
    }
  ],
  "recipes": [
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": "recipes/default.rb",
      "specificity": "default",
      "name": "default.rb",
      "checksum": "7e79b1ace7728fdsadfsdaf857e60fc69"
    }
  ],
  "providers": [

  ],
  "resources": [

  ],
  "templates": [
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": "templates/default/chef-getting-started.txt.erb",
      "specificity": "default",
      "name": "chef-getting-started.txt.erb",
      "checksum": "a29d6f2545sdffds1f140c3a78b1fe"
    }
  ],
  "root_files": [
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": ".DS_Store",
      "specificity": "default",
      "name": ".DS_Store",
      "checksum": "c107b500aafd12asdffdsdf5c2a7d6"
    },
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": "metadata.json",
      "specificity": "default",
      "name": "metadata.json",
      "checksum": "20f09570e54dasdf0f3ae01e6401c90f"
    },
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": "metadata.rb",
      "specificity": "default",
      "name": "metadata.rb",
      "checksum": "71027aefasd487fdsa4cb6994b66ed"
    },
    {
      "url": "https://domain.com/org_name/(...rest of URL)",
      "path": "README.rdoc",
      "specificity": "default",
      "name": "README.rdoc",
      "checksum": "8b9275e56fee974easdfasdfbb729"
    }
  ],
  "name": "getting-started-0.4.0",
  "frozen?": false,
  "version": "0.4.0",
  "json_class": "Chef::CookbookVersion",
  "metadata": {
    "maintainer": "Maintainer",
    "attributes": { },
    "suggestions": { },
    "recipes": { "getting-started": "" },
    "dependencies": { },
    "platforms": { },
    "groupings": { },
    "recommendations": { },
    "name": "getting-started",
    "description": "description",
    "version": "0.4.0",
    "maintainer_email": "sysadmin@opscode.com",
    "long_description": "= DESCRIPTION:\n\nThis cookbook is used to do some things.\n\n",
    "providing": { "getting-started": ">= 0.0.0" },
    "replacing": { },
    "conflicting": { },
    "license": "Apache 2.0"
  }
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

PUT

The PUT method is used to create or update a cookbook version.

This method has no parameters.

Request

PUT /organizations/ORG_NAME/cookbooks/NAME/VERSION

with a request body that looks something like:

{
  "definitions": [
    {
      "name": "unicorn_config.rb",
      "checksum": "c92b659171552e896074caa58dada0c2",
      "path": "definitions/unicorn_config.rb",
      "specificity": "default"
    }
  ],
  "name": "unicorn-0.1.2",
  "attributes": [],
  "files": [],
  "json_class": "Chef::CookbookVersion",
  "providers": [],
  "metadata": {
    "dependencies": {"ruby": [], "rubygems": []},
    "name": "unicorn",
    "maintainer_email": "ops@opscode.com",
    "attributes": {},
    "license": "Apache 2.0",
    "suggestions": {},
    "platforms": {},
    "maintainer": "Opscode, Inc",
    "long_description": "= LICENSE AND AUTHOR:\n\nAuthor:: Adam Jacob...",
    "recommendations": {},
    "version": "0.1.2",
    "conflicting": {},
    "recipes": {"unicorn": "Installs unicorn rubygem"},
    "groupings": {},
    "replacing": {},
    "description": "Installs/Configures unicorn",
    "providing": {}
  },
  "libraries": [],
  "templates": [
    {
      "name": "unicorn.rb.erb",
      "checksum": "36a1cc1b225708db96d48026c3f624b2",
      "path": "templates/default/unicorn.rb.erb",
      "specificity": "default"
    }
  ],
  "resources": [],
  "cookbook_name": "unicorn",
  "version": "0.1.2",
  "recipes": [
    {
      "name": "default.rb",
      "checksum": "ba0dadcbca26710a521e0e3160cc5e20",
      "path": "recipes/default.rb",
      "specificity": "default"
    }
  ],
  "root_files": [
    {
      "name": "README.rdoc",
      "checksum": "d18c630c8a68ffa4852d13214d0525a6",
      "path": "README.rdoc",
      "specificity": "default"
    },
    {
      "name": "metadata.rb",
      "checksum": "967087a09f48f234028d3aa27a094882",
      "path": "metadata.rb",
      "specificity": "default"
    },
    {
      "name": "metadata.json",
      "checksum": "45b27c78955f6a738d2d42d88056c57c",
      "path": "metadata.json",
      "specificity": "default"
    }
  ],
  "chef_type": "cookbook_version"
}

where the checksum values must have already been uploaded to the Chef server using the sandbox endpoint. Once a file with a particular checksum has been uploaded by the user, redundant uploads are not necessary. Unused checksum values will be garbage collected.

Response

This method has no response body.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/data

A data bag is a global variable that is stored as JSON data and is accessible from a Chef server. A data bag is indexed for searching and can be loaded by a recipe or accessed during a search.

The /data endpoint has the following methods: GET and POST.

GET

The GET method is used to return a list of all data bags on the Chef server.

This method has no parameters.

Request

GET /organizations/ORG_NAME/data

Response

The response will return something like the following:

{
  "users": "http://localhost:4000/data/users",
  "applications": "http://localhost:4000/data/applications"
}

shown as a list of key-value pairs, where (in the example above) users and applications are the names of data bags and “http://localhost:4000/data/foo” is the path to the data bag.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create a new data bag on the Chef server.

This method has no parameters.

Request

POST /organizations/ORG_NAME/data

with a request body that contains the key-value pair for the data bag and looks something like:

{
  "name": "users"
}

where (in the example above) name is the key and “users” is the value.

Response

The response will return something like the following:

{
   "chef_type" => "environment"
   "data_bag" => "data123"
   "id" => "12345"
}

Response Codes

Response Code Description
201 Created. The object was created.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Unauthorized. The user which made the request is not authorized to perform the action.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/data/NAME

The /data/NAME endpoint is used to view and update data for a specific data bag. This endpoint has the following methods: GET and POST.

GET

The GET method is used to return a hash of all entries in the specified data bag.

This method has no parameters.

Request

GET /organizations/ORG_NAME/data/NAME

Response

The response will return something like the following:

{
   "adam": "http://localhost:4000/data/users/adam"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

POST

The POST method is used to create a new data bag item.

This method has no parameters.

Request

POST /organizations/ORG_NAME/data/NAME

with a request body that looks something like:

{
  "id": "adam",
  "real_name": "Adam Jacob"
}

where id is required.

Response

This method has no response body.

Response Codes

Response Code Description
200 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/data/NAME/ITEM

A data bag is a container of related data bag items, where each individual data bag item is a JSON file. The only structural requirement of a data bag item is that it must have an id:

{
  "id": "ITEM_NAME",
  "key": "value"
}

where key and value are the key:value pair for each additional attribute within the data bag item. knife can load a data bag item by specifying the name of the data bag to which the item belongs and then the filename of the data bag item.

The /data/NAME/ITEM endpoint allows the key-value pairs within a data bag item to be viewed and managed. This endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete a key-value pair in a data bag item.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME/data/NAME/ITEM

This method has no request body.

Response

The response will return something like the following:

{
  "id": "adam",
  "real_name": "Adam Brent Jacob"
}

where the key-value pairs represent the last state of the data bag item.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to view all of the key-value pairs in a data bag item.

This method has no parameters.

Request

GET /organizations/ORG_NAME/data/NAME/ITEM

Response

The response will return something like the following:

{
  "real_name": "Adam Jacob",
  "id": "adam"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

PUT

The PUT method is used to replace the contents of a data bag item with the contents of this request.

This method has no parameters.

Request

POST /organizations/ORG_NAME/data/NAME/ITEM

with a request body that looks something like:

{
  "real_name": "Adam Brent Jacob",
  "id": "adam"
}

where id is required.

Response

The response will return something like the following:

{
  "real_name": "Adam Brent Jacob",
  "id": "adam"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/environments

An environment is a way to map an organization’s real-life workflow to what can be configured and managed when using Chef server. Every organization begins with a single environment called the _default environment, which cannot be modified (or deleted). Additional environments can be created to reflect each organization’s patterns and workflow. For example, creating production, staging, testing, and development environments. Generally, an environment is also associated with one (or more) cookbook versions.

The /environments endpoint has the following methods: GET and POST.

GET

The GET method is used to return a data structure that contains a link to each available environment.

This method has no parameters.

Request

GET /organizations/ORG_NAME/environments

Response

The response will return something like the following:

{
  "_default": "https://api.opscode.com/organizations/org_name/environments/_default",
  "webserver": "https://api.opscode.com/organizations/org_name/environments/webserver"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create a new environment.

This method has no parameters.

Request

POST /organizations/ORG_NAME/environments

with a request body that looks something like:

{
  "name": "dev",
  "attributes": {},
  "json_class": "Chef::Environment",
  "description": "",
  "cookbook_versions": {},
  "chef_type": "environment"
}

Response

The response will return something like the following:

{ "uri": "http://localhost:4000/environments/dev" }

Response Codes

Response Code Description
201 Created. The object was created.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/environments/NAME

The /environments/NAME endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete an environment.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME/environments/NAME

Response

The response will return the JSON for the environment that was deleted, something like the following:

{
  "name":"backend",
  "description":"",
  "cookbook_versions":{},
  "json_class":"Chef::Environment",
  "chef_type":"environment",
  "default_attributes":{},
  "override_attributes":{}
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to return the details for an environment as JSON.

This method has no parameters.

Request

GET /organizations/ORG_NAME/environments/NAME

Response

The response will return something like the following:

{
  "name": "_default",
  "description": "The default Chef environment",
  "json_class": "Chef::Environment",
  "chef_type": "environment",
  "default_attributes": { }
  "override_attributes": { },
  "cookbook_versions": { },
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

PUT

The PUT method is used to update the details of an environment on the Chef server.

This method has no parameters.

Request

PUT /organizations/ORG_NAME/environments/NAME

with a request body that contains the updated JSON for the environment and looks something like:

{
  "name": "dev",
  "attributes": {},
  "json_class": "Chef::Environment",
  "description": "The Dev Environment",
  "cookbook_versions": {},
  "chef_type": "environment"
}

Response

The response will return the updated environment.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/environments/n/cookbooks/n

The /environments/NAME/cookbooks/NAME endpoint has the following methods: GET.

GET

The GET method is used to return a hash of key-value pairs for the requested cookbook.

This method has the following parameters:

Parameter Description
num_versions=n The number of cookbook versions to include in the response, where n is the number of cookbook versions. For example: num_versions=3 will return the three latest versions, in descending order (newest to oldest). Use num_versions=all to return all cookbook versions. If num_versions is not specified, it will return a single cookbook version. 0 is an invalid input (it will return an empty array for the versions of each cookbook).

Request

GET /organizations/ORG_NAME/environments/NAME/cookbooks/NAME

where the first instance of NAME is the name of the environment, and the second instance is the name of the cookbook.

Response

The response will return something like the following:

{
  "apache2" => {
    "url" => "http://localhost:4000/cookbooks/apache2",
    "versions" => [
      {"url" => "http://localhost:4000/cookbooks/apache2/5.1.0",
       "version" => "5.1.0"},
      {"url" => "http://localhost:4000/cookbooks/apache2/4.2.0",
       "version" => "4.2.0"}
    ]
  }
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/environments/n/cookbook_versions

The /environments/NAME/cookbook_versions endpoint has the following methods: POST.

POST

The POST method is used to return a hash of the cookbooks and cookbook versions (including all dependencies) that are required by the run_list array. Version constraints may be specified using the @ symbol after the cookbook name as a delimiter. Version constraints may also be present when the cookbook_versions attributes is specified for an environment or when dependencies are specified by a cookbook.

This method has no parameters.

Request

POST /organizations/ORG_NAME/environments/NAME/cookbook_versions

with a request body that looks something like:

{
  "run_list": [
    "zed@0.0.1",
    "bar",
    "mysql",
    "gem",
    "nginx@0.99.2",
    "cron",
    "foo"
  ]
}

where @x.x.x represents a constraint for a cookbook version.

Response

The response will return a list of cookbooks that are required by the run_list array contained in the request. The cookbooks that are returned are often the latest versions of each cookbook. Depending on any constraints present in the request or on dependencies a cookbook may have for specific cookbook versions, a request may not always return the latest cookbook version for each cookbook.

A response looks something like the following:

{
  "cookbook_name": {
    "recipes": [
      {
        "name": "default.rb",
        "path": "recipes/default.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "recipe_name.rb",
        "path": "recipes/recipe_name.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        ...
      }
    ],
    "definitions": [

    ],
    "libraries": [

    ],
    "attributes": [

    ],
    "files": [

    ],
    "templates": [
      {
        "name": "template_name.erb",
        "path": "templates/default/template_name.erb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        ...
      }
    ],
    "resources": [

    ],
    "providers": [

    ],
    "root_files": [
      {
        "name": "metadata.rb",
        "path": "metadata.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      }
    ],
    "cookbook_name": "cookbook_name-1.0.2",
    "metadata": {
      "name": "cookbook_name",
      "description": "description",
      "long_description": "",
      "maintainer": "maintainer",
      "maintainer_email": "maintainer@email.com",
      "license": "license",
      "platforms": {
      },
      "dependencies": {
        "cookbook_name": ">= 0.0.0",
        "cookbook_name": ">= 1.2.3",
        ...
        "cookbook_name": ">= 0.1.0"
      },
      "recommendations": {
      },
      "suggestions": {
      },
      "conflicting": {
      },
      "providing": {
        "cookbook_name": ">= 0.0.0",
        "cookbook_name::recipe_name": ">= 0.0.0",
        "cookbook_name::recipe_name": ">= 1.2.3",
        "cookbook_name::recipe_name": ">= 0.1.0"
      },
      "replacing": {
      },
      "attributes": {
      },
      "groupings": {
      },
      "recipes": {
        "cookbook_name": "description",
        "cookbook_name::recipe_name": "",
        ...
        "cookbook_name::recipe_name": ""
      },
      "version": "0.0.0"
    },
    "version": "0.0.0",
    "name": "cookbook_name-1.0.2",
    "frozen?": false,
    "chef_type": "cookbook_version",
    "json_class": "Chef::CookbookVersion"
  },
  "cookbook_name": {
     "recipes": [
      {
        "name": "default.rb",
        "path": "recipes/default.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
    ],
    "definitions": [

    ],
    "libraries": [
      {
        "name": "library_file.rb",
        "path": "libraries/library_file.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      }
    ],
    "attributes": [
      {
        "name": "default.rb",
        "path": "attributes/default.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      }
    ],
    "files": [

    ],
    "templates": [

    ],
    "resources": [

    ],
    "providers": [

    ],
    "root_files": [
      {
        "name": ".gitignore",
        "path": ".gitignore",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": ".kitchen.yml",
        "path": ".kitchen.yml",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "CHANGELOG.md",
        "path": "CHANGELOG.md",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "CONTRIBUTING",
        "path": "CONTRIBUTING",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "LICENSE",
        "path": "LICENSE",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "metadata.json",
        "path": "metadata.json",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "metadata.rb",
        "path": "metadata.rb",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
      {
        "name": "README.md",
        "path": "README.md",
        "checksum": "12345efg78912346abcddefg789",
        "specificity": "default",
        "url": "https://URL"
      },
    ],
    "chef_type": "cookbook_version",
    "name": "cookbook_name-1.0.2",
    "cookbook_name": "cookbook_name",
    "version": "1.0.2",
    "metadata": {
      "name": "cookbook_name",
      "description": "description",
      "long_description": "",
      "maintainer": "maintainer",
      "maintainer_email": "maintainer@email.com",
      "license": "license",
      "platforms": {
      },
      "dependencies": {
      },
      "recommendations": {
      },
      "suggestions": {
      },
      "conflicting": {
      },
      "providing": {
      },
      "replacing": {
      },
      "attributes": {
      },
      "groupings": {
      },
      "recipes": {
      },
      "version": "1.0.2"
    },
    "frozen?": true,
    "json_class": "Chef::CookbookVersion"
  },
  "cookbook_name": {
   ...
  }
}

Response Codes

Response Code Description
200 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
412 Not allowed. A set of cookbooks and/or cookbook versions could not be found that met all of the requirements of the run-list. A cookbook in the run-list may not exist. A dependency may be present for a cookbook that does not exist. A constraint on a cookbook made by a run-list, environment, or cookbook version may not match an available cookbook version.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/environments/NAME/cookbooks

The /environments/NAME/cookbooks endpoint has the following methods: GET.

GET

The GET method is used to get a list of cookbooks and cookbook versions that are available to the specified environment.

This method has the following parameters:

Parameter Description
num_versions=n The number of cookbook versions to include in the response, where n is the number of cookbook versions. For example: num_versions=3 will return the three latest versions, in descending order (newest to oldest). Use num_versions=all to return all cookbook versions. If num_versions is not specified, it will return a single cookbook version. 0 is an invalid input (it will return an empty array for the versions of each cookbook).

Request

GET /organizations/ORG_NAME/environments/NAME/cookbooks

Response

The response will return something like the following:

{
  "apache2" => {
    "url" => "http://localhost:4000/cookbooks/apache2",
    "versions" => [
      {"url" => "http://localhost:4000/cookbooks/apache2/5.1.0",
       "version" => "5.1.0"},
      {"url" => "http://localhost:4000/cookbooks/apache2/4.2.0",
       "version" => "4.2.0"}
    ]
  },
  "nginx" => {
    "url" => "http://localhost:4000/cookbooks/nginx",
    "versions" => [
      {"url" => "http://localhost:4000/cookbooks/nginx/1.0.0",
       "version" => "1.0.0"},
      {"url" => "http://localhost:4000/cookbooks/nginx/0.3.0",
       "version" => "0.3.0"}
    ]
  }
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/environments/NAME/nodes

The /environments/NAME/nodes endpoint has the following methods: GET.

GET

The GET method is used to return a list of nodes in a given environment.

This method has no parameters.

Request

GET /organizations/ORG_NAME/environments/NAME/nodes

Response

The response will return something like the following:

{
  "blah": "https://api.opscode.com/org/org_name/nodes/_default",
  "boxer": "https://api.opscode.com/org/org_name/nodes/frontend",
  "blarrrrgh": "https://api.opscode.com/org/org_name/nodes/backend"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/environments/NAME/recipes

The /environments/NAME/recipes endpoint has the following methods: GET.

GET

The GET method is used to return a list of recipes available to a given environment.

This method has no parameters.

Request

GET /organizations/ORG_NAME/environments/NAME/recipes

where the first instance of NAME is the name of the environment, and the second instance is the name of the recipe.

Response

The response will return something like the following:

[
  "ant",
  "apache2",
  "apache2::mod_auth_openid",
  "apache2::mod_authnz_ldap",
  "apt",
  "aws",
  "capistrano",
  "chef",
  "chef::bootstrap_client",
  "chef-client::config",
  "chef-client",
  ...
]

The list of recipes will be the default recipes for a given cookbook. If an environment has multiple versions of a cookbook that matches its constraints, only the recipes from the latest version of that cookbook will be reported.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/environments/NAME/roles/NAME

The /environments/NAME/roles/NAME endpoint has the following methods: GET.

GET

The GET method is used to return the run_list attribute of the role (when the name of the environment is _default) or to return env_run_lists[environment_name] (for non-default environments).

Note

The behavior of this endpoint is identical to GET /roles/NAME/environments/NAME; it is recommended (but not required) that GET /roles/NAME/environments/NAME be used instead of this endpoint.

This method has no parameters.

Request

GET /organizations/ORG_NAME/environments/NAME/roles/NAME

where the first instance of NAME is the name of the environment, and the second instance is the name of the role.

Response

The response will return something like the following:

{
  "run_list": [
    "recipe[recipe_name]",
    "role[role_name]",
    "recipe[recipe_name]",
    "role[role_name]",
    "recipe[recipe_name]",
    "role[role_name]"
  ]
}

The chef-client will pick up the _default run-list if env_run_list[environment_name] is null or nonexistent.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/nodes

A node is any physical, virtual, or cloud machine that is configured to be maintained by a chef-client.

The /nodes endpoint has the following methods: GET and POST.

GET

The GET method is used to return a hash of URIs for nodes on the Chef server.

This method has no parameters.

Request

GET /organizations/ORG_NAME/nodes

Response

The response will return something like the following:

{
  "latte": "http://localhost:4000/nodes/latte"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create a new node.

This method has no parameters.

Request

POST /organizations/ORG_NAME/nodes

with a request body that looks something like:

{
  "name": "latte",
  "chef_type": "node",
  "json_class": "Chef::Node",
  "attributes": {
    "hardware_type": "laptop"
  },
  "overrides": {},
  "defaults": {},
  "run_list": [ "recipe[unicorn]" ]
}

where name is the name of the node. Other attributes are optional. The order of the run_list attribute matters.

Response

The response will return something like the following:

{ "uri": "http://localhost:4000/nodes/latte" }

Response Codes

Response Code Description
201 Created. The object was created.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/nodes/NAME

The /nodes/NAME endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete a node.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME/nodes/NAME

Response

The response will return the last known state of the node, similar to:

{
  "overrides": {},
  "name": "latte",
  "chef_type": "node",
  "json_class": "Chef::Node",
  "attributes": {
    "hardware_type": "laptop"
  },
  "run_list": [
    "recipe[apache2]"
  ],
  "defaults": {}
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to return the details of a node as JSON.

This method has no parameters.

Request

GET /organizations/ORG_NAME/nodes/NAME

Response

The response will return something like the following:

{
  "name": "node_name",
  "chef_environment": "_default",
  "run_list": [
    "recipe[recipe_name]"
  ]
  "json_class": "Chef::Node",
  "chef_type": "node",
  "automatic": { ... },
  "normal": { "tags": [ ] },
  "default": { },
  "override": { }
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

PUT

The PUT method is used to update a node.

This method has no parameters.

Request

PUT /organizations/ORG_NAME/nodes/NAME

with a request body that looks something like:

{
  "overrides": {},
  "name": "latte",
  "chef_type": "node",
  "json_class": "Chef::Node",
  "attributes": {
    "hardware_type": "laptop"
  },
  "run_list": [
    'recipe[cookbook_name::recipe_name],
    role[role_name]'
  ],
  "defaults": {}
}

Response

The response will return the updated node.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/principals/NAME

The /principals/NAME endpoint has the following methods: GET.

GET

The GET method is used to get a list of public keys for clients and users in order to ensure that enough information is present for authorized requests.

This method has no parameters.

Request

GET /organizations/ORG_NAME/principals/NAME

Response

The response will return something like the following for a user:

{
  "name": "normal_user",
  "type": "user",
  "public_key": "-----BEGIN PUBLIC KEY-----\n
                MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyVPW9YXa5PR0rgEW1updSxygB\n
                wmVpDnHurgQ7/gbh+PmY49EZsfrZSbKgSKy+rxdsVoSoU+krYtHvYIwVfr2tk0FP\n
                nhAWJaFH654KpuCNG6x6iMLtzGO1Ma/VzHnFqoOeSCKHXDhmHwJAjGDTPAgCJQiI\n
                eau6cDNJRiJ7j0/xBwIDAQAB\n
                -----END PUBLIC KEY-----"
}

or something like the following for a client:

{
  "name": "client_node",
  "type": "client",
  "public_key": "-----BEGIN PUBLIC KEY-----\n
                MIEfGVG0GCSqGSIb3DQEBAQUAA4RRFEDCVgftg67j8dgsdfges0rgEW1updSxygB\n
                wmVpDnHuqwe7/gbh+PmY49EZsfrZSbKgSKy+rxKJHREGJ5tgCtHvYIwVfr2tk0FP\n
                nhAWJaFH654KpuCNG6x6iMLt5FGH1Ma/VzHnFqoOeSCKHDhmHwJAjGDTPAgCJQiI\n
                elk8UFCN45Jj0/xBwIDAQAB\n
                -----END PUBLIC KEY-----"
}

Response Codes

Response Code Description
200 OK. The request was successful.
404 Not found. The requested object does not exist.

/roles

A role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role’s run list are applied to the node’s configuration details. When a chef-client runs, it merges its own attributes and run lists with those contained within each assigned role.

The /roles endpoint has the following methods: GET and POST.

GET

The GET method is used to get a list of roles along with their associated URIs.

This method has no parameters.

Request

GET /organizations/ORG_NAME/roles

Response

The response will return something like the following:

{
  "webserver": "http://localhost:4000/roles/webserver"
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.

POST

The POST method is used to create a new role on the Chef server.

This method has no parameters.

Request

POST /organizations/ORG_NAME/roles

with a request body that looks something like:

{
  "name": "webserver",
  "chef_type": "role",
  "json_class": "Chef::Role",
  "default_attributes": {},
  "description": "A webserver",
  "run_list": [
    "recipe[unicorn]",
    "recipe[apache2]"
  ],
  "override_attributes": {}
}

Response

The response will return something like the following:

{ "uri": "http://localhost:4000/roles/webserver" }

Response Codes

Response Code Description
201 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/roles/NAME

The /roles/NAME endpoint has the following methods: GET, DELETE, and PUT.

DELETE

The DELETE method is used to delete a role on the Chef server.

This method has no parameters.

Request

DELETE /organizations/ORG_NAME/roles/NAME

Response

The response will return something like the following:

{
  "name": "webserver",
  "chef_type": "role",
  "json_class": "Chef::Role",
  "default_attributes": {},
  "description": "A webserver",
  "run_list": [
    "recipe[apache2]"
  ],
  "override_attributes": {}
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

GET

The GET method is used to return the details for a role as JSON.

This method has no parameters.

Request

GET /organizations/ORG_NAME/roles/NAME

Response

The response will return something like the following:

{
  "name": "webserver",
  "chef_type": "role",
  "json_class": "Chef::Role",
  "default_attributes": {},
  "description": "A webserver",
  "run_list": [
    "recipe[unicorn]",
    "recipe[apache2]"
  ],
  "override_attributes": {}
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

PUT

The PUT method is used to update a role on the Chef server.

This method has no parameters.

Request

PUT /organizations/ORG_NAME/roles/NAME

with a request body that looks something like:

{
  "name": "webserver",
  "chef_type": "role",
  "json_class": "Chef::Role",
  "default_attributes": {},
  "description": "A webserver",
  "run_list": [
    "recipe[apache2]"
  ],
  "override_attributes": {}
}

Response

The response will return the JSON for the updated role.

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/roles/NAME/environments

The /roles/NAME/environments endpoint has the following method: GET.

GET

The GET method returns a list of the environments that have environment-specific run-lists in the given role as JSON data.

This method has no parameters.

Request

GET /organizations/ORG_NAME/roles/NAME/environments

Response

The response will return something like the following:

["_default","production","qa"]

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/roles/NAME/environments/NAME

The /roles/NAME/environments/NAME endpoint has the following method: GET.

GET

The GET method returns the environment-specific run-list (env_run_lists[environment_name]) for a role.

This method has no parameters.

Request

GET /organizations/ORG_NAME/roles/NAME/environments/NAME

where the first NAME is the name of the role and the second is the name of the environment.

Response

The response will return something like the following:

{"run_list":["recipe[foo]"]}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

/sandboxes

A sandbox is used to commit files so they only need to be updated one time, as opposed to every time a cookbook is uploaded. The /sandboxes endpoint has the following methods: POST.

POST

The POST method is used to create a new sandbox. This method accepts a list of checksums as input and returns the URLs against which to PUT files that need to be uploaded.

This method has no parameters.

Request

POST /organizations/ORG_NAME/sandboxes

with a request body that looks something like:

{"checksums": {
  "385ea5490c86570c7de71070bce9384a":null,
  "f6f73175e979bd90af6184ec277f760c":null,
  "2e03dd7e5b2e6c8eab1cf41ac61396d5":null
  }
}

Response

The response will return something like the following:

{"uri":
 "https://api.opscode.com/organizations/testorg/sandboxes/eff7b6f8b3ef44c6867216662d5eeb5f",
 "checksums":
   {"385ea5490c86570c7de71070bce9384a":
     {"url":
      "https://s3.amazonaws.com/opscode-platform-production-data/organization-(...)",
       "needs_upload":true},
       "f6f73175e979bd90af6184ec277f760c"=>
     {"url":
       "https://s3.amazonaws.com/opscode-platform-production-data/organization-(...)",
       "needs_upload":true},
       "2e03dd7e5b2e6c8eab1cf41ac61396d5":
     {"url":
       "https://s3.amazonaws.com/opscode-platform-production-data/organization-(...)",
       "needs_upload":true}
   },
 "sandbox_id"=>"eff7b6f8b3ef44c6867216662d5eeb5f"
}

Response Codes

Response Code Description
200 OK. The request was successful. A hash that maps each checksum to a hash that contains a boolean needs_upload field and a URL if needs_upload is set to true.
400 Bad request. The object has already been committed or one (or more) of the objects were not properly uploaded. The payload does not contain a well-formed checksums parameter that is a hash containing a key for each checksum.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/sandboxes/ID

Each sandbox has a unique identifier. The /sandboxes/ID endpoint has the following methods: PUT.

PUT

The PUT method is used to commit files that are in a sandbox to their final location so that changes to cookbooks will not require re-uploading the same data.

This method has no parameters.

Request

PUT /organizations/ORG_NAME/sandboxes/ID

with a request body that looks something like:

{"is_completed":true}

Response

The response will return something like the following:

{
  "guid": guid,
  "name": guid,
  "checksums":
    {"385ea5490c86570c7de71070bce9384a":
    {"url":
      "https://s3.amazonaws.com/opscode-platform-production-data/organization-(...)",
      "needs_upload":true}
  },
  "create_time": <get an example of time format>,
  "is_completed": true
}

Response Codes

Response Code Description
200 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
413 Request entity too large. A request may not be larger than 1000000 bytes.

/search/INDEX

Use the /search/INDEX endpoint to access the search indexes on the Chef server. The /search/INDEX endpoint has the following methods: GET and POST.

A search query is comprised of two parts: the key and the search pattern. A search query has the following syntax:

key:search_pattern

where key is a field name that is found in the JSON description of an indexable object on the Chef server (a role, node, client, environment, or data bag) and search_pattern defines what will be searched for, using one of the following search patterns: exact, wildcard, range, or fuzzy matching. Both key and search_pattern are case-sensitive; key has limited support for multiple character wildcard matching using an asterisk (“*”) (and as long as it is not the first character).

GET

The GET method is used to return all of the data that matches the query in the GET request.

This method has the following parameters:

Parameter Description
q The search query used to identify a a list of items on a Chef server. This option uses the same syntax as the search sub-command.
rows The number of rows to be returned.
sort The order in which search results will be sorted.
start The row at which return results will begin.

Request

GET /organizations/ORG_NAME/search/INDEX

Response

The response contains the total number of rows that match the request and will return something like the following:

{
 "total": 1,
 "start": 0,
 "rows": [
    {
     "overrides": {"hardware_type": "laptop"},
     "name": "latte",
     "chef_type": "node",
     "json_class": "Chef::Node",
     "attributes": {"hardware_type": "laptop"},
     "run_list": ["recipe[unicorn]"],
     "defaults": {}
    }
  ]
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.

POST

A partial search query allows a search query to be made against specific attribute keys that are stored on the Chef server. A partial search query can search the same set of objects on the Chef server as a full search query, including specifying an object index and providing a query that can be matched to the relevant index. While a full search query will return an array of objects that match (each object containing a full set of attributes for the node), a partial search query will return only the values for the attributes that match. One primary benefit of using a partial search query is that it requires less memory and network bandwidth while the chef-client processes the search results.

Note

To use the partial_search method in a recipe, that recipe must contain a dependency on the partial_search cookbook.

To create a partial search query, use the partial_search method, and then specify the key paths for the attributes to be returned. Each key path should be specified as an array of strings and is mapped to an arbitrary short name. For example:

partial_search(:node, 'role:web',
  :keys => { 'name' => [ 'name' ],
             'ip'   => [ 'ipaddress' ],
             'kernel_version' => [ 'kernel', 'version' ]
           }
).each do |result|
  puts result['name']
  puts result['ip']
  puts result['kernel_version']
end

In the previous example, two attributes will be extracted (on the Chef server) from any node that matches the search query. The result will be a simple hash with keys name, ip, and kernel_version.

The POST method is used to return partial search results. For example, if a node has the following:

{
  'x' => 'foo',
  'kernel' => { 'a' => 1, 'foo' => 'bar', 'version' => [ 1, 2, 3 ] }
}

a partial search query can be used to return something like:

{ 'kernel_version' => [ 1, 2, 3 ] }

This method has the following parameters:

Parameter Description
q The search query used to identify a a list of items on a Chef server. This option uses the same syntax as the search sub-command.
rows The number of rows to be returned.
sort The order in which search results will be sorted.
start The row at which return results will begin.

Request

GET /organizations/ORG_NAME/search

with a request body that looks something like:

{
  'name' => [ 'name' ],
  'ip'   => [ 'ipaddress' ],
  'kernel_version' => [ 'kernel', 'version' ]
}

Response

The response will return something like the following:

{
  "name": "latte",
  "ip": "123.4.5.6789",
  "kernel_version": {"linux": "1.2.3"},
}

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
413 Request entity too large. A request may not be larger than 1000000 bytes.

_status

The /_status endpoint can be used to check the status of communications between the front and back end servers. This endpoint is located at /_status on the front end servers.

Request

api.get("https://chef_server.front_end.url/_status")

This method has no request body.

Response

The response will return something like the following:

{
  "status" => "pong",
  "upstreams" =>
    {
      "service_name" => "pong",
      "service_name" => "pong",
      ...
    }
 }

Response Codes

Response Code Description
200 All communications are OK.
500

One (or more) services are down. For example:

{
  "status":"fail",
  "upstreams":
    {
      "service_name":"fail",
      "service_name":"pong",
      ...
    }
}

/updated_since

The /updated_since endpoint ensures that replica instances of the Chef server are able to synchronize with the primary Chef server. The /ORGS/ORG_NAME/updated_since endpoint has the following methods: GET.

GET

The GET method is used to return the details of an organization as JSON.

Request

GET /organizations/ORG_NAME/objects_since?seq=NUM

where NUM is the largest integer previously returned as an identifier.

Response

The response will return an array of paths for objects that have been created, updated, or deleted since NUM, similar to:

[
  {
    "action": "create",
    "id": 1,
    "path": "/roles/foo"
  },
  {
    "action": "create",
    "id": 2,
    "path": "/roles/foo2"
  },
  {
    "action": "create",
    "id": 3,
    "path": "/roles/foo3"
  },
  {
    "action": "update",
    "id": 4,
    "path": "/roles/foo3"
  }
]

Response Codes

Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user which made the request is not authorized to perform the action.
403 Forbidden. The user which made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.