Chef DSM API

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

Requirements

The Chef DSM API has the following requirements:

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 DSM API that’s being used.
A request must be signed by adding authentication headers. ‘Mixlib::Authentication’ may be used to sign requests.
A request must be well-formatted. The easiest way to ensure a well-formatted request is to use the Chef::ServerAPI library.

Authentication Headers

Authentication to the Chef DSM requires a specific set of HTTP headers signed using a private key associated with the client making the request. The request is authorized if the Chef DSM can verify the signature using the public key. Only authorized actions are allowed.

Note

Most authentication requests made to the Chef DSM are abstracted from the user, such as when using a Knife. 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 doesn’t require authentication headers. In a few cases, such as using arbitrary Ruby code, a Chef DSM API client, or cURL, it may be necessary to include the full authentication header as part of the request to the Chef DSM.

Required Headers

The following authentication headers are required:

Feature	Description
`Accept`	The format in which response data from the Chef DSM is provided. This header must be set to `application/json`.
`Content-Type`	The format in which data is sent to the Chef DSM. 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` doesn't need to be specified.) For example: `api.chef.io` (which is the same as `api.chef.io:80`) or `api.chef.io:443`.
`Method`	The method from the request.
`Path`	Omit for Authentication Version 1. Specify for Authentication Version 1.3
`X-Chef-Version`	The version of the Chef Infra Client executable from which a request is made. This header ensures that responses are in the correct format. For example: `12.0.2` or `11.16.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, for example `X-Ops-Authorization-1`, `X-Ops-Authorization-2`, `X-Ops-Authorization-N`, where `N` represents the integer used by the last header that's part of the request.
`X-Ops-Content-Hash`	For API Version 1. The result of the SHA-1 hash of the request body encoded using Base64. Base64 encoding should have line breaks every 60 characters. For API Version 1.3. The result of the SHA-256 hash of the request body encoded using Base64. Base64 encoding should have line breaks every 60 characters.
`X-Ops-Server-API-Version`	Use `X-Ops-Server-API-Version` to specify the version of the Chef DSM API. For example: `X-Ops-Server-API-Version: 1`. `X-Ops-Server-API-Version: 0` is supported for use with Chef DSM version 12, but will be deprecated as part of the next major release.
`X-Ops-Sign`	Set this header to the following value: `algorithm=sha1,version=1.0` or `version=1.3`.
`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.

Note

Use X-Ops-Server-API-Info to identify the version of the Chef DSM API.

Canonical Header Format 1.0 using SHA-1

The signed headers are encrypted using the OpenSSL RSA_private_encrypt method and encoded in Base64. The signed headers are used to create one or more X-Ops-Authorization-N headers of 60 character segments. The canonical header should be created by concatenating the following headers, encrypting and encoding:

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 (for example, GET or POST)
HASHED_PATH is the path of the request: /organizations/NAME/name_of_endpoint. The HASHED_PATH must be hashed using SHA-1 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.
X-Ops-Content-Hash is the Base64 encoded SHA256 hash of the json body of the request.
X-Ops-Timestamp UTC time in RFC3339 format.
X-Ops-UserId is the plain text client or user name.

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

Example

The following example shows an authentication request:

GET /organizations/NAME/nodes HTTP/1.1
  Accept: application/json
  Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
  Host: api.chef.io:443
  User-Agent: Chef Knife/12.0.2 (ruby-2.1.1-p320; ohai-8.0.0; x86_64-darwin12.0.2; +http://chef.io)
  X-Chef-Version: 12.0.2
  X-Ops-Authorization-1: BE3NnBritishaf3ifuwLSPCCYasdfXaRN5oZb4c6hbW0aefI
  X-Ops-Authorization-2: sL4j1qtEZzi/2WeF67UuytdsdfgbOc5CjgECQwqrym9gCUON
  X-Ops-Authorization-3: yf0p7PrLRCNasdfaHhQ2LWSea+kTcu0dkasdfvaTghfCDC57
  X-Ops-Authorization-4: 155i+ZlthfasfasdffukusbIUGBKUYFjhbvcds3k0i0gqs+V
  X-Ops-Authorization-5: /sLcR7JjQky7sdafIHNfsBQrISktNPower1236hbFIayFBx3
  X-Ops-Authorization-6: nodilAGMb166@haC/fttwlWQ2N1LasdqqGomRedtyhSqXA==
  X-Ops-Content-Hash: 2jmj7l5rfasfgSw0ygaVb/vlWAghYkK/YBwk=
  X-Ops-Server-API-Info: 1
  X-Ops-Sign: algorithm=sha1;version=1.0;
  X-Ops-Userid: user_id
  X-Ops-Timestamp: 2014-12-12T17:13:28Z

Canonical Header Format 1.3 using SHA-256

Chef DSM versions 12.4.0 and above support signing protocol version 1.3, which supports for SHA-256 algorithms. It can be enabled on Chef Infra Client with the client.rb file:

authentication_protocol_version = '1.3'

And for Chef’s knife CLI with config.rb:

knife[:authentication_protocol_version] = '1.3'

To create the signed headers for direct use. Gather the following headers in the order listed, convert the signature headers to a concatenated string, sign and Base64 encode the result. The concatenation of signature headers is signed using the client RSA private key, with SHA-256 hashing and PKCS1v15 padding. Chop the Base64 encoded value into 60 character chunks and create X-Ops-Authorization-N headers with the chunks.

Method:HTTP_METHOD
Path:PATH
X-Ops-Content-Hash:HASHED_BODY
X-Ops-Sign
X-Ops-Timestamp:TIME
X-Ops-UserId:USERID
X-Ops-Server-API-Version

where:

HTTP_METHOD is the method used in the API request (GET, POST, …)
PATH is the path of the request: /organizations/NAME/name_of_endpoint. The value must not have repeated forward slashes (/), must not end in a forward slash (unless the path is /), and must not include a query string.
X-Ops-Content-Hash is the Base64 encoded SHA256 hash of the json body of the request.
X-Ops-Sign has the value version=1.3.
X-Ops-Timestamp UTC time in RFC3339 format.
X-Ops-UserId is the plain text client or user name.
X-Ops-Server-API-Version is the numeric value of the Chef DSM API.

Example

The following example shows an authentication request:

GET /organizations/NAME/nodes HTTP/1.1
  Accept: application/json
  Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
  Host: api.chef.io:443
  Method: GET
  Path: /organizations/NAME/nodes
  User-Agent: Chef Knife/12.0.2 (ruby-2.1.1-p320; ohai-8.0.0; x86_64-darwin12.0.2; +http://chef.io)
  X-Chef-Version: 14.0.0
  X-Ops-Content-Hash: 2jmj7l5rfasfgSw0ygaVb/vlWAghYkK/YBwk=
  X-Ops-Authorization-1: BE3NnBritishaf3ifuwLSPCCYasdfXaRN5oZb4c6hbW0aefI
  X-Ops-Authorization-2: sL4j1qtEZzi/2WeF67UuytdsdfgbOc5CjgECQwqrym9gCUON
  X-Ops-Authorization-3: yf0p7PrLRCNasdfaHhQ2LWSea+kTcu0dkasdfvaTghfCDC57
  X-Ops-Authorization-4: 155i+ZlthfasfasdffukusbIUGBKUYFjhbvcds3k0i0gqs+V
  X-Ops-Authorization-5: /sLcR7JjQky7sdafIHNfsBQrISktNPower1236hbFIayFBx3
  X-Ops-Authorization-6: nodilAGMb166@haC/fttwlWQ2N1LasdqqGomRedtyhSqXA==
  X-Ops-Server-API-Info: 1
  X-Ops-Sign: version=1.3;
  X-Ops-Timestamp: 2014-12-12T17:13:28Z
  X-Ops-Userid: user_id

Knife API Requests

A knife plugin is a set of one (or more) subcommands that can be added to knife to support additional functionality that isn’t built-in to the base set of knife subcommands. Many of the knife plugins are built by members of the Chef community and several of them are built and maintained by Chef.

A knife plugin can be used to make authenticated API requests to the Chef DSM using the following methods:

Method	Description
`rest.delete_rest`	Use to delete an object from Chef DSM.
`rest.get_rest`	Use to get the details of an object on Chef DSM.
`rest.post_rest`	Use to add an object to Chef DSM.
`rest.put_rest`	Use to update an object on Chef DSM.

For example:

module MyCommands
  class MyNodeDelete < Chef::Knife
    #An implementation of knife node delete
    banner 'knife my node delete [NODE_NAME]'

    def run
      if name_args.length < 1
        show_usage
        ui.fatal('You must specify a node name.')
        exit 1
      end
      nodename = name_args[0]
      api_endpoint = "nodes/#{nodename}"
      # Again, we could just call rest.delete_rest
      nodey = rest.get_rest(api_endpoint)
      ui.confirm("Do you really want to delete #{nodey}")
      nodey.destroy
    end
  end
end

Global Endpoints

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

/authenticate_user

The /authenticate_user endpoint has the following methods: POST.

POST

The POST method is used to authenticate a user. This endpoint is used by the Chef Identity Service to authenticate users of Chef Supermarket to the Chef DSM. This method has no parameters.

Request

POST /authenticate_user

with a request body similar to:

{
  "username" : "grantmc",
  "password" : "p@ssw0rd"
}

Response

This method has no response body.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, password, and that the correct key was used to sign the request.

/license

Note

This endpoint is used for information purposes only and to trigger a notification in the Chef management console about the number of licenses owned vs. the number of licenses that should be owned. No other action is taken, and the functionality and behavior of the Chef DSM and any added component don’t change.

The /license endpoint has the following methods: GET.

GET

The GET method is used to get license information for the Chef DSM. This method has no parameters.

Request

GET /license

This method has no request body.

Response

The response is similar to:

{
  "limit_exceeded": false,
  "node_license": 25,
  "node_count": 12,
  "upgrade_url": "https://www.chef.io/pricing"
}

When node_count is greater than node_license, then limit_exceeded is true, and the Chef management console will display a notification about this status. The way to resolve this is to visit the upgrade URL, add the appropriate number of licenses, and then update the configuration settings appropriately.

The chef-server.rb file contains settings that can be used to edit the number of nodes that are under license:

Setting	Description
`license['nodes']`	The number of licensed nodes. Default value: `25`.
`license['upgrade_url']`	The URL to visit for more information about how to update the number of nodes licensed for an organization. Default value: `"https://www.chef.io/pricing"`.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

/organizations

The Chef DSM may contain multiple organizations. The /organizations endpoint has the following methods: GET and POST.

Warning

This endpoint may only be accessed by the pivotal user, which is created as part of the installation process for the Chef DSM. (See the “Query for Users and Orgs” example below on how to access this endpoint with the pivotal user.)

GET

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

Request

GET /organizations

Response

The response is similar to:

{
  "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 who made the request isn't authorized to perform the action.

POST

The POST method is used to create an organization on the Chef DSM. This method has no parameters.

Request

POST /organizations

with a request body similar to:

{
  "name": "org_name1",
  "full_name": "Org_name1 Full Name"
}

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-whitespace 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 is similar to:

{
  "clientname": "org_name1-validator",
  "private_key": "-----BEGIN RSA PRIVATE KEY----- MIIEpQIBAAKCAQEAx2uyX ...",
  "uri": "https://url/for/org_name1"
}

Response codes

Response Code	Description
`201`	Created. The request was successful. The organization was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`409`	Conflict. The organization already exists.

/organizations/NAME

An organization is a single instance of a Chef DSM, including all the nodes that are managed by that Chef DSM and each of the workstations that will run knife and access the Chef DSM using the Chef DSM 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/NAME

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`403`	Forbidden. The user who made the request isn't 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 is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

PUT

The PUT method is used to update an organization definition. This method has no parameters.

Request

PUT /organizations/NAME

with a request body similar to:

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

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`400`	Bad request. The contents of the request aren't formatted correctly.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`410`	Gone. Unable to update private key.

/_stats

Use the /_stats endpoint to display statistics about connection pool usage inside Erchef, PostgreSQL, and the Erlang VM. The _stats endpoint uses Basic authorization instead of the X-Ops-Authorization scheme usually used to connect to the Chef DSM. The default user used to query the _stats endpoint is statsuser. The password for the statsuser is available as the opscode_erchef::stats_password from the chef-server-ctl show-service-credentials command.

The /_stats endpoint has the following method: GET.

GET

The GET method is used to get the statistics. This method has the following parameters:

Parameter	Description
`format=json`	Return results as JSON.
`format=text`	Return results as text.

Request

GET /_stats

This method has no parameters. This method has no request body. The /_stats endpoint doesn’t require authentication headers.

Response

The response body is similar to:

[
  {
    "name": "erlang_vm_time_correction",
    "type": "UNTYPED",
    "help": "1 if time correction is enabled, otherwise 0.",
    "metrics": [
      {
        "value": "1"
      }
    ]
  },
  {
    "name": "erlang_vm_thread_pool_size",
    "type": "GAUGE",
    "help": "The number of async threads in the async thread pool used for asynchronous driver calls.",
    "metrics": [
      {
        "value": "5"
      }
    ]
  },

  ...

  {
    "name": "pg_stat_seq_scan",
    "type": "COUNTER",
    "help": "Number of sequential scans initiated on all tables",
    "metrics": [
      {
        "value": "22147"
      }
    ]
  }
]

Response codes

Response Code	Description
`200`	OK.
`401`	Unauthorized. The user or password isn't valid.
`406`	Not Acceptable. An invalid format was requested.

/_status

Use the /_status endpoint to check the status of communications between the front and back end servers. This endpoint is located at /_status on the front end servers. The /_status endpoint doesn’t require authentication headers.

GET

The GET method is used to get the Chef DSM status details.

Request

GET /_status

This method has no parameters. This method has no request body.

Response

The response will return something like the following:

{
  "status": "pong",
  "upstreams":
    {
      "service_name": "pong",
      "service_name": "pong",
      ...
    }
  "keygen":
    {
      "keys": 10,
      ....
    }
 }

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", ... } }`

/users

A user is an individual account created to allow access to Chef DSM. For example, a user that operates the workstation or host that Chef DSM is managed from.

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

Warning

This endpoint may only be accessed by the pivotal user, which is created as part of the Chef DSM installation process. (See the “Query for Users and Orgs” example below for an example of how to access this endpoint with the pivotal user.)

Note

This documentation for the /users endpoint is for version 1 of the Chef DSM API. Version 0 of the API has some differences in the request body and in the results.

GET

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

This method has the following parameters:

Parameter	Description
`email=jane@chef.com`	Filter the users returned based on their email id.
`external_authentication_uid=jane@chef.com`	Filter the users returned based on their external login id.
`verbose=true`	Returns a user list with `email`, `first_name`, and `last_name` fields. If this flag is set, the `email` and `external_authentication_uid` parameters are ignored.

Request

GET /users

Response

The response is similar to:

{
  "user1": "https://chef.example/users/user1",
  "user2": "https://chef.example/users/user2"
}

The verbose response is similar to:

{
  "janechef": { "email": "jane.chef@user.com", "first_name": "jane", "last_name": "chef_user" },
  "yaelsmith": { "email": "yeal.chef@user.com", "first_name": "yeal", "last_name": "smith" }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

Optional filtering

Filtering on /users can be done with the external_authentication_uid. This is to support SAML authentication.

As an example, to retrieve users whose external_authentication_uid is jane@example.com, you would do the following:

GET /users?external_authentication_uid=jane%40example.com

POST

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

This method has no parameters.

Request

POST /users

with a request body similar to:

{
  "username": "robert-forster",
  "display_name": "robert",
  "email": "robert@noreply.com",
  "first_name": "robert",
  "last_name": "forster",
  "middle_name": "",
  "password": "yeahpass",
  "create_key": true,
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoYyN0AIhUh7Fw1+gQtR+ \n0/HY3625IUlVheoUeUz3WnsTrUGSSS4fHvxUiCJlNni1sQvcJ0xC9Bw3iMz7YVFO\nWz5SeKmajqKEnNywN8/NByZhhlLdBxBX/UN04/7aHZMoZxrrjXGLcyjvXN3uxyCO\nyPY989pa68LJ9jXWyyfKjCYdztSFcRuwF7tWgqnlsc8pve/UaWamNOTXQnyrQ6Dp\ndn+1jiNbEJIdxiza7DJMH/9/i/mLIDEFCLRPQ3RqW4T8QrSbkyzPO/iwaHl9U196\n06Ajv1RNnfyHnBXIM+I5mxJRyJCyDFo/MACc5AgO6M0a7sJ/sdX+WccgcHEVbPAl\n1wIDAQAB \n-----END PUBLIC KEY-----\n\n"
}

where:

username must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores. For example: chef. username is required to be present and have a valid value. A valid username is a dot separated list of elements matching a-z0-9!#$%&'*+/=?^_`{|}~-.
display_name is required to be present.
email is required to be present and have a valid value. The email validation doesn’t allow for all unicode characters.
Either external_authentication_uid or password are required to be present and have a value.
During the POST, the public_key value will be broken out and resubmitted to the keys portion of the API in the latest Chef DSM versions.
Only one of the keys, create_key or public_key, may be specified. If create_key is specified, a default private key is generated and returned.

Response

The response is similar to:

{
  "uri": "https://chef.example/users/robert-forster",
  "chef_key": {
    "name": "default",
    "public_key": "-----BEGIN RSA PUBLIC KEY...",
    "expiration_date": "infinity",
    "uri": "https://chef.example/users/robert-forster/keys/default",
    "private_key": "-----BEGIN RSA PRIVATE KEY..."
  }
}

Response codes

Response Code	Description
`201`	OK. The user was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't 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.

/users/NAME

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

Note

This documentation for the /users/NAME endpoint is for version 1 of the Chef DSM API. Version 0 of the API has some differences in the request body and in the results.

DELETE

The DELETE method is used to delete a user. This method has no parameters.

Request

DELETE /users/USER_NAME

Response

The response is similar to:

{
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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 is similar to:

{
  "username": "robert-forster",
  "display_name": "robert",
  "email": "robert@noreply.com",
  "first_name": "robert",
  "last_name": "forster"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method updates a specific user. If values aren’t specified for the PUT method, the Chef DSM will use the existing values rather than assign default values.

Note

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

Note

As of 12.1.0, the "public_key", "private_key", and "create_key" parameters in PUT requests to clients/users will cause a 400 response.

This method has no parameters.

Request

PUT /users/NAME

with a request body similar to:

{
  "username":     "grant.mclennan",
  "display_name": "Grant McLennan",
  "email":        "grant@newlocation.com",
  "first_name":   "Grant",
  "last_name":    "McLennan",
  "middle_name":  "james",
  "public_key" : "-------- BEGIN PUBLIC KEY ----and a valid key here"
}

Response

The response is similar to:

{
  "uri": "https://chef.example/users/grant.mclennan",
  "chef_key": {
    "name": "default",
    "public_key": "-----BEGIN RSA PUBLIC KEY...",
    "expiration_date": "infinity",
    "uri": "https://chef.example/users/rober-forster/keys/default",
    "private_key": ""
  }
}

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.)
`400`	Invalid. Invalid or missing values. Otherwise malformed request.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`409`	Conflict. 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.

/users/USER/keys/

The /users/USER/keys endpoint has the following methods: GET and POST. User keys are public RSA keys in the SSL .pem file format and are used for authentication. The Chef DSM doesn’t save private keys for users.

GET

The GET method is used to retrieve all of the named user’s key identifiers, associated URIs, and expiry states. This method has no parameters.

Request

GET /users/USER/keys/

Response

The response is similar to:

[
  {
    "name" : "default",
    "uri" : "https://chef.example/users/USER/keys/default",
    "expired" : false
  },
  {
    "name" : "key1",
    "uri" : "https://chef.example/users/USER/keys/key1",
    "expired" : false
  }
]

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

POST

The POST method is used to add a key for the specified user. This method has no parameters.

Request

POST /users/USER/keys/

with a request body similar to:

{
  "name" : "key1",
  "public_key" : "-------- BEGIN PUBLIC KEY ----and a valid key here",
  "expiration_date" : "infinity"
}

Response

The response is similar to:

{
  "name" : "key1",
  "uri" : "https://chapi_chef_server.mdef.example/users/user1/keys/key1",
  "expired": false
}

Response codes

Response Code	Description
`201`	Created. The object was created.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/users/USER/keys/KEY

The /users/USER/keys/KEY endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete the specified key for the specified user. This method has no parameters.

Request

DELETE /users/USER/keys/KEY

Response

The response returns the information about the deleted key and is similar to:

{
  "name" : "default",
  "public_key" : "-------- BEGIN PUBLIC KEY --------- ...",
  "expiration_date" : "2020-12-31T00:00:00Z"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return details for a specific key for a specific user. This method has no parameters.

Request

GET /users/USER/keys/KEY

Response

The response is similar to:

{
  "name" : "default",
  "public_key" : "-------- BEGIN PUBLIC KEY --------- ...",
  "expiration_date" : "2020-12-31T00:00:00Z"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method is used to update one or more properties for a specific key for a specific user. This method has no parameters.

Request

PUT /users/USER/keys/KEY

with a request body similar to:

{
  "name" : "new_key_name",
  "public_key" : "-------- BEGIN PUBLIC KEY ----and a valid key here",
  "expiration_date" : "2020-12-31T00:00:00Z"
}

Response

The response contains the updated information for the key, and is similar to:

{
  "name" : "new_key_name",
  "public_key" : "-------- BEGIN PUBLIC KEY --------- ...",
  "expiration_date" : "2020-12-31T00:00:00Z"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`201`	Created. The object was created.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

Organization endpoints

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

GET /organizations/NAME/roles

where ORG_NAME is the name of the organization.

/association_requests

Users may be invited to join organizations with the web user interface in the Chef management console or with the POST endpoint in the Chef DSM API.

The /association_requests endpoint has the following methods: DELETE, GET, and POST.

DELETE

The DELETE method is used to delete a pending invitation. This method has no parameters.

Request

DELETE /organizations/NAME/association_requests/ID

This method has no request body.

Response

The response is similar to:

{
  "id":      "79b9382ab70e962907cee1747f9969a4",
  "orgname": "testorg",
  "username" "janedoe"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to get a list of pending invitations. This method has no parameters.

Request

GET /organizations/NAME/association_requests

This method has no request body.

Response

The response returns a dictionary similar to:

[
  {
    "id": "79b9382ab70e962907cee1747f9969a4",
    "username": "marygupta"
  },
  {
    "id": "24t1432uf33x799382abb7096g8190b5",
    "username": "johnirving"
  }
]

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

The POST method is used to create an invitation. This method has no parameters.

Request

{
 "user": "billysmith"
}

POST /organizations/NAME/association_requests

Response

The response is similar to:

{
  "uri": "https://chef.example/organizations/test/association_requests/79b9382ab70e962907cee1747f9969a4",
  "organization_user": {
    "username": "authorizeduser"
  },
  "organization": {
    "name": "test"
  },
  "user": {
    "email": "sallyjane@domain.org",
    "first_name": "sally"
  }
}

Response codes

Response Code	Description
`201`	OK. An invitation was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The invited user doesn't exist.
`409`	Conflict. The object already exists.

/clients

Use the /clients endpoint to manage clients and their associated RSA key-pairs. The /clients endpoint has the following methods: GET and POST.

Note

The clients should be managed using a knife as opposed to the Chef DSM API. The interactions between clients, , and acls are tricky.

GET

The GET method is used to return a client list on the Chef DSM, including clients for nodes that have been registered with the Chef DSM, the chef-validator clients, and the chef-server-webui clients for the entire organization. This method has no parameters.

Request

GET /organizations/NAME/clients

This method has no request body.

Response

The response is similar to:

{
  "org1-validator" : "https://chef.example/orgaizations/org1/clients/org1-validator",
  "client1" : "https://chef.example/orgaizations/org1/clients/client1"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

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

Note

As of 12.1.0, the "admin" parameter is no longer supported in client/user creation and support. If used in the POST or PUT of a client or user, the "admin" parameter is ignored.

This method has no parameters.

Request

POST /organizations/NAME/clients

with a request body similar to:

{
  "name": "name_of_API_client",
  "clientname": "name_of_API_client",
  "validator": true,
  "create_key": true
}

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. Either name or clientname needs to be specified.

Response

The response is similar to:

{
  "uri": "https://chef.example/orgaizations/org1/clients/client1",
  "chef_key": {
    "name": "default",
    "expiration_date": "infinity",
    "private_key": "-----BEGIN RSA PRIVATE KEY----- ...",
    "public_key": "-----BEGIN PUBLIC KEY----- ... ",
    "uri": "https://chef.example/orgaizations/org1/clients/client1/keys/default"
}

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

Response codes

Response Code	Description
`201`	Created. The client was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't 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 client. This endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to remove a specific client. This method has no parameters.

Request

DELETE /organizations/NAME/clients/NAME

This method has no request body.

Response

The response has no body.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return a specific API client. This method has no parameters.

Request

GET /organizations/NAME/clients/NAME

This method has no request body.

Response

The response is similar to:

{
  "name": "user1",
  "clientname": "user1",
  "orgname": "test",
  "json_class": "Chef::ApiClient",
  "chef_type": "client",
  "validator": "false"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method updates a specific client. If values aren’t specified for the PUT method, the Chef DSM will use the existing values rather than assign default values.

Note

PUT supports renames. If PUT /client/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.

Note

As of 12.1.0, the "admin" parameter is no longer supported in client/user creation and support. If used in the POST or PUT of a client or user, then it’s ignored.

Note

As of 12.1.0, including "public_key", "private_key", or "create_key" in PUT requests to clients/users will cause a 400 response.

Note

"name" and "clientname" aren’t independent values. Making a PUT request with different values will return a 400 error. Either name may be specified to set both values.

Request

PUT /organizations/NAME/clients/NAME

with a request body similar to:

{
  "name": "monkeypants",
  "validator": false
}

Response

The response is similar to:

{
  "name": "monkeypants",
  "clientname": "monkeypants",
  "validator": true,
  "json_class":"Chef::ApiClient",
  "chef_type":"client"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`201`	Created. The client was updated. (This response code is only returned when the client is renamed.)
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`409`	Conflict. This response code is only returned when a client is renamed, but a client already exists with the new name.
`413`	Request entity too large. A request may not be larger than 1000000 bytes.

/clients/CLIENT/keys/

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

GET

The GET method is used to retrieve all of the named client’s key identifiers, associated URIs, and expiry states. This method has no parameters.

Request

GET /organizations/NAME/clients/CLIENT/keys

This method has no request body.

Response

The response is similar to:

[
  {
     "name": "default",
     "uri": "https://chef.example/organizations/example/clients/client1/keys/default",
     "expired": false
  },
  {
     "name": "key1",
     "uri": "https://chef.example/organizations/example/clients/client1/keys/key1",
     "expired": true
  }
]

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

POST

The POST method is used to add a key for the specified client.

This method has no parameters.

Request

POST /organizations/NAME/clients/CLIENT/keys

with a request body similar to:

{
  "name": "key1",
  "public_key": "-------- BEGIN PUBLIC KEY ----and a valid key here",
  "expiration_date": "infinity"
}

Response

The response is similar to:

{
  "uri": "https://chef.example/organizations/example/clients/client1/keys/key1"
}

Response codes

Response Code	Description
`201`	Created. The object was created.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/clients/CLIENT/keys/KEY

The /clients/CLIENT/keys/KEY endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete the specified key for the specified client. This method has no parameters.

Request

DELETE /organizations/NAME/clients/CLIENT/keys/KEY

This method has no request body.

Response

The response returns the information about the deleted key and is similar to:

{
  "name": "default",
  "public_key": "-------- BEGIN PUBLIC KEY --------- ...",
  "expiration_date": "2020-12-31T00:00:00Z"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return details for a specific key for a specific client. This method has no parameters.

Request

GET /organizations/NAME/clients/CLIENT/keys/KEY

This method has no request body.

Response

The response is similar to:

{
  "name" : "default",
  "public_key" : "-------- BEGIN PUBLIC KEY --------- ...",
  "expiration_date" : "2020-12-31T00:00:00Z"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method is used to update one or more properties for a specific key for a specific client. This method has no parameters.

Request

PUT /organizations/NAME/clients/CLIENT/keys/KEY

with a request body similar to:

{
  "name": "new_key_name",
  "public_key": "-------- BEGIN PUBLIC KEY ----and a valid key here",
  "expiration_date": "2020-12-31T00:00:00Z"
}

Response

The response contains the updated information for the key and is similar to:

{
  "name": "new_key_name",
  "public_key": "-------- BEGIN PUBLIC KEY --------- ...",
  "expiration_date": "2020-12-31T00:00:00Z"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`201`	Created. The object was created.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/containers

The /containers endpoint has the following methods: GET, POST.

GET

The GET method is used to get a list of containers. This method has no parameters.

Note

The /containers endpoint isn’t useful outside of the Chef DSM code.

Request

GET /organizations/NAME/containers

This method doesn’t use a request body.

Response

The response is similar to:

{
  "clients": "https://chef.example/organizations/example/containers/clients",
  "containers": "https://chef.example/organizations/example/containers/containers",
  "cookbooks": "https://chef.example/organizations/example/containers/cookbooks",
  "data": "https://chef.example/organizations/example/containers/data",
  "environments": "https://chef.example/organizations/example/containers/environments",
  "groups": "https://chef.example/organizations/example/containers/groups",
  "nodes": "https://chef.example/organizations/example/containers/nodes",
  "roles": "https://chef.example/organizations/example/containers/roles",
  "sandboxes": "https://chef.example/organizations/example/containers/sandboxes"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

POST

The POST method is used to create a container. Using the POST method of the /containers endpoint may have unexpected effects and likely break your system. Use of this method isn’t supported. This method has no parameters.

Request

POST /organizations/NAME

This method has a request body similar to:

{
  "containername": "mycontainer",
  "containerpath": "mycontainer"
}

Response

The response is similar to:

{
  "uri"": "https://chef.example/organizations/test/containers/mycontainer"
}

Response codes

Response Code	Description
`201`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/containers/NAME

DELETE

The DELETE method is used to remove a container.

The /containers/Name endpoint has the following methods: DELETE, GET. This method has no parameters.

Note

Using the DELETE method of the /containers/NAME endpoint may have unexpected effects and is likely to break your system. Use of this method isn’t supported.

Request

DELETE /organizations/NAME/containers/NAME

This method doesn’t use a request body.

Response

The response doesn’t return response body.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to get a container. This method has no parameters.

Request

GET /organizations/NAME/containers/NAME

This method doesn’t use a request body.

Response

The response is similar to:

{
  "containername"": "mycontainer",
  "containerpath"": "mycontainer"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/cookbook_artifacts

Cookbook artifacts are specific versions of cookbooks that were specified by a Policyfile applied to a node.

The /organization/NAME/cookbook_artifacts endpoint has the following methods: GET.

GET

The GET method returns a hash of all cookbook artifacts and their versions. This method has no parameters.

Request

GET /organizations/NAME/cookbook_artifacts

This method has no request body.

Response

The response is similar to:

{
  "oc-influxdb": {
    "url": "https://chef.example/organizations/example-org/cookbook_artifacts/oc-influxdb",
    "versions": [
      {
        "url": "https://chef.example/organizations/example-org/cookbook_artifacts/oc-influxdb/9634a5d998b02ff069761f6e1309a41572d0f858",
        "identifier": "9634a5d998b02ff069761f6e1309a41572d0f858"
      },
      {
        "url": "https://chef.example/organizations/example-org/cookbook_artifacts/oc-influxdb/d774c9bb079f21b64c34275ecd4b371e0cae71a1",
        "identifier": "d774c9bb079f21b64c34275ecd4b371e0cae71a1"
      }
    ]
  },
    "rabbitmq": {
    "url": "https://chef.example/organizations/example-org/cookbook_artifacts/rabbitmq",
    "versions": [
      {
        "url": "https://chef.example/organizations/example-org/cookbook_artifacts/rabbitmq/58035a5b41c005f3b5b98f22ccaed1a0d6161e22",
        "identifier": "58035a5b41c005f3b5b98f22ccaed1a0d6161e22"
      },
      {
        "url": "https://chef.example/organizations/example-org/cookbook_artifacts/rabbitmq/5c08f92cc01f94ee37d382c32023b137ee343a1e",
        "identifier": "5c08f92cc01f94ee37d382c32023b137ee343a1e"
      }
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

/cookbook_artifacts/NAME

This endpoint lists versions of a named cookbook artifact.

The /organization/NAME/cookbook_artifacts/NAME endpoint has the following methods: GET.

GET

The GET method is used to return a hash of a single cookbook artifact and its versions. This method has no parameters.

Request

GET /organizations/NAME/cookbook_artifacts/NAME

This method has no request body.

Response

The response is similar to:

{
  "rabbitmq": {
    "url": "https://chef.example/organizations/example-org/cookbook_artifacts/rabbitmq",
    "versions": [
      {
        "url": "https://chef.example/organizations/example-org/cookbook_artifacts/rabbitmq/0bd7539be0434e3355aff8ecccf4543ecf5c4be2",
        "identifier": "0bd7539be0434e3355aff8ecccf4543ecf5c4be2"
      },
      {
        "url": "https://chef.example/organizations/example-org/cookbook_artifacts/rabbitmq/0e1016d364685b87456c648136da04a2559821ec",
        "identifier": "0e1016d364685b87456c648136da04a2559821ec"
      }
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/cookbook_artifacts/NAME/ID

The /organization/NAME/cookbook_artifacts/NAME/ID endpoint has the following methods: DELETE, GET, and PUT.

DELETE

The DELETE method is used to delete a single cookbook artifact version. This method has no parameters.

Request

DELETE /organizations/NAME/cookbook_artifacts/NAME/ID

This method has no request body.

Response

The response contains the record of the deleted resource and is similar to:

{
  "version": "5.7.7",
  "name": "rabbitmq",
  "identifier": "f3cf8ea7d8bfc59e35ec541946e3e82cd4b73e74",
  "frozen?": false,
  "chef_type": "cookbook_version",
  "attributes": [
    {
      "name": "default.rb",
      "path": "attributes/default.rb",
      "checksum": "e5a530cca3898d8bd07604435dc5156e",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-e5a530cca3898d8bd07604435dc5156e"
    }
  ],
  "definitions": [
  ],
  "files": [
  ],
  "libraries": [
    {
      "name": "matchers.rb",
      "path": "libraries/matchers.rb",
      "checksum": "24c3f44c4d1d62300a56051f0069f639",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-24c3f44c4d1d62300a56051f0069f639"
    },
    {
      "name": "helpers.rb",
      "path": "libraries/helpers.rb",
      "checksum": "df65c4a7259fcb30c6f3f1305ebf7502",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-df65c4a7259fcb30c6f3f1305ebf7502"
    },
    {
      "name": "default.rb",
      "path": "libraries/default.rb",
      "checksum": "94292faac84ba797e720501700b30f74",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-94292faac84ba797e720501700b30f74"
    }
  ],
  "providers": [
    {
      "name": "user.rb",
      "path": "providers/user.rb",
      "checksum": "c31c9cc749f21962c825f983a6679d94",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-c31c9cc749f21962c825f983a6679d94"
    },
    {
      "name": "policy.rb",
      "path": "providers/policy.rb",
      "checksum": "746c8a3f248f5bbfa51f5d2ba60b6315",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-746c8a3f248f5bbfa51f5d2ba60b6315"
    }
  ],
  "recipes": [
    {
      "name": "default.rb",
      "path": "recipes/default.rb",
      "checksum": "99a9b404ff6038d6ac55a90ca68c347a",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-99a9b404ff6038d6ac55a90ca68c347a"
    },
    {
      "name": "cluster.rb",
      "path": "recipes/cluster.rb",
      "checksum": "fc0a86c1f858c9d37e11282efc9fe329",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-fc0a86c1f858c9d37e11282efc9fe329"
    }
  ],
  "resources": [
    {
      "name": "cluster.rb",
      "path": "resources/cluster.rb",
      "checksum": "85e74276e19bfdad581dce4f5c59f94a",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-85e74276e19bfdad581dce4f5c59f94a"
    }
  ],
  "root_files": [
    {
      "name": "metadata.rb",
      "path": "metadata.rb",
      "checksum": "36b395e758138a4295d1e3f9b3df5da9",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-36b395e758138a4295d1e3f9b3df5da9"
    },
    {
      "name": "README.md",
      "path": "README.md",
      "checksum": "99873670f0994642f5e6baade52c8020",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-99873670f0994642f5e6baade52c8020"
    }
  ],
  "templates": [
    {
      "name": "default.rabbitmq-server.erb",
      "path": "templates/default/default.rabbitmq-server.erb",
      "checksum": "077855f4dc37f7fb708976134d8b2551",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-077855f4dc37f7fb708976134d8b2551"
    },
    {
      "name": "90forceyes.erb",
      "path": "templates/default/90forceyes.erb",
      "checksum": "73cc571097cf77c74b4e7b5b680020c9",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-73cc571097cf77c74b4e7b5b680020c9"
    }
  ],
  "metadata": {
    "name": "rabbitmq",
    "description": "Installs and configures RabbitMQ server",
    "long_description": "",
    "maintainer": "Chef Software, Inc. and contributors",
    "maintainer_email": "mklishin@pivotal.io",
    "license": "Apache-2.0",
    "platforms": {
      "amazon": ">= 2.0",
      "centos": ">= 7.0",
      "debian": ">= 8.0",
      "opensuse": ">= 0.0.0",
      "opensuseleap": ">= 0.0.0",
      "oracle": ">= 0.0.0",
      "redhat": ">= 0.0.0",
      "scientific": ">= 0.0.0",
      "smartos": ">= 0.0.0",
      "suse": ">= 0.0.0",
      "ubuntu": ">= 14.04"
    },
    "dependencies": {
      "erlang": ">= 0.0.0",
      "yum-epel": ">= 0.0.0",
      "yum-erlang_solutions": ">= 0.0.0",
      "dpkg_autostart": ">= 0.0.0",
      "logrotate": ">= 0.0.0"
    },
    "providing": {
      "rabbitmq::cluster": ">= 0.0.0",
      "rabbitmq::community_plugins": ">= 0.0.0",
      "rabbitmq": ">= 0.0.0",
      "rabbitmq::erlang_package": ">= 0.0.0",
      "rabbitmq::esl_erlang_package": ">= 0.0.0",
      "rabbitmq::management_ui": ">= 0.0.0",
      "rabbitmq::mgmt_console": ">= 0.0.0",
      "rabbitmq::plugin_management": ">= 0.0.0",
      "rabbitmq::plugins": ">= 0.0.0",
      "rabbitmq::policies": ">= 0.0.0",
      "rabbitmq::policy_management": ">= 0.0.0",
      "rabbitmq::systemd_limits": ">= 0.0.0",
      "rabbitmq::user_management": ">= 0.0.0",
      "rabbitmq::users": ">= 0.0.0",
      "rabbitmq::vhosts": ">= 0.0.0",
      "rabbitmq::virtualhost_management": ">= 0.0.0"
    },
    "recipes": {
      "rabbitmq": "Install and configure RabbitMQ",
      "rabbitmq::systemd_limits": "Sets up kernel limits (for example nofile) for RabbitMQ with systemd",
      "rabbitmq::cluster": "Set up RabbitMQ clustering.",
      "rabbitmq::management_ui": "Sets up RabbitMQ management plugin/UI",
      "rabbitmq::mgmt_console": "Deprecated, alias for rabbitmq::management_ui",
      "rabbitmq::plugins": "Manage plugins with node attributes",
      "rabbitmq::plugin_management": "Deprecated, alias for rabbitmq::plugins",
      "rabbitmq::vhosts": "Manage virtual hosts with node attributes",
      "rabbitmq::virtualhost_management": "Deprecated, alias for rabbitmq::vhosts",
      "rabbitmq::users": "Manage users with node attributes",
      "rabbitmq::user_management": "Deprecated, alias for rabbitmq::users",
      "rabbitmq::policies": "Manage policies with node attributes",
      "rabbitmq::policy_management": "Deprecated, alias for rabbitmq::policies",
      "rabbitmq::erlang_package": "Provisions Erlang with Team RabbitMQ packages",
      "rabbitmq::esl_erlang_package": "Alias for erlang::esl",
      "rabbitmq::community_plugins": ""
    },
    "version": "5.7.7",
    "source_url": "https://github.com/rabbitmq/chef-cookbook",
    "issues_url": "https://github.com/rabbitmq/chef-cookbook/issues",
    "privacy": false,
    "chef_versions": [
    ],
    "ohai_versions": [
    ],
    "gems": [
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return a single cookbook artifact version. This method has no parameters.

Request

GET /organizations/NAME/cookbook_artifacts/NAME/ID

This method has no request body.

Response

The response is similar to:

{
  "version": "5.7.7",
  "name": "rabbitmq",
  "identifier": "f3cf8ea7d8bfc59e35ec541946e3e82cd4b73e74",
  "frozen?": false,
  "chef_type": "cookbook_version",
  "attributes": [
    {
      "name": "default.rb",
      "path": "attributes/default.rb",
      "checksum": "e5a530cca3898d8bd07604435dc5156e",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-e5a530cca3898d8bd07604435dc5156e"
    }
  ],
  "definitions": [
  ],
  "files": [
  ],
  "libraries": [
    {
      "name": "matchers.rb",
      "path": "libraries/matchers.rb",
      "checksum": "24c3f44c4d1d62300a56051f0069f639",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-24c3f44c4d1d62300a56051f0069f639"
    },
    {
      "name": "helpers.rb",
      "path": "libraries/helpers.rb",
      "checksum": "df65c4a7259fcb30c6f3f1305ebf7502",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-df65c4a7259fcb30c6f3f1305ebf7502"
    },
    {
      "name": "default.rb",
      "path": "libraries/default.rb",
      "checksum": "94292faac84ba797e720501700b30f74",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-94292faac84ba797e720501700b30f74"
    }
  ],
  "providers": [
    {
      "name": "user.rb",
      "path": "providers/user.rb",
      "checksum": "c31c9cc749f21962c825f983a6679d94",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-c31c9cc749f21962c825f983a6679d94"
    },
    {
      "name": "policy.rb",
      "path": "providers/policy.rb",
      "checksum": "746c8a3f248f5bbfa51f5d2ba60b6315",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-746c8a3f248f5bbfa51f5d2ba60b6315"
    }
  ],
  "recipes": [
    {
      "name": "default.rb",
      "path": "recipes/default.rb",
      "checksum": "99a9b404ff6038d6ac55a90ca68c347a",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-99a9b404ff6038d6ac55a90ca68c347a"
    },
    {
      "name": "cluster.rb",
      "path": "recipes/cluster.rb",
      "checksum": "fc0a86c1f858c9d37e11282efc9fe329",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-fc0a86c1f858c9d37e11282efc9fe329"
    }
  ],
  "resources": [
    {
      "name": "cluster.rb",
      "path": "resources/cluster.rb",
      "checksum": "85e74276e19bfdad581dce4f5c59f94a",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-85e74276e19bfdad581dce4f5c59f94a"
    }
  ],
  "root_files": [
    {
      "name": "metadata.rb",
      "path": "metadata.rb",
      "checksum": "36b395e758138a4295d1e3f9b3df5da9",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-36b395e758138a4295d1e3f9b3df5da9"
    },
    {
      "name": "README.md",
      "path": "README.md",
      "checksum": "99873670f0994642f5e6baade52c8020",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-99873670f0994642f5e6baade52c8020"
    }
  ],
  "templates": [
    {
      "name": "default.rabbitmq-server.erb",
      "path": "templates/default/default.rabbitmq-server.erb",
      "checksum": "077855f4dc37f7fb708976134d8b2551",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-077855f4dc37f7fb708976134d8b2551"
    },
    {
      "name": "90forceyes.erb",
      "path": "templates/default/90forceyes.erb",
      "checksum": "73cc571097cf77c74b4e7b5b680020c9",
      "specificity": "default",
      "url": "https://chef.example/bookshelf/organization-9f69768696feedcd165633b8b475cc0b/checksum-73cc571097cf77c74b4e7b5b680020c9"
    }
  ],
  "metadata": {
    "name": "rabbitmq",
    "description": "Installs and configures RabbitMQ server",
    "long_description": "",
    "maintainer": "Chef Software, Inc. and contributors",
    "maintainer_email": "mklishin@pivotal.io",
    "license": "Apache-2.0",
    "platforms": {
      "amazon": ">= 2.0",
      "centos": ">= 7.0",
      "debian": ">= 8.0",
      "opensuse": ">= 0.0.0",
      "opensuseleap": ">= 0.0.0",
      "oracle": ">= 0.0.0",
      "redhat": ">= 0.0.0",
      "scientific": ">= 0.0.0",
      "smartos": ">= 0.0.0",
      "suse": ">= 0.0.0",
      "ubuntu": ">= 14.04"
    },
    "dependencies": {
      "erlang": ">= 0.0.0",
      "yum-epel": ">= 0.0.0",
      "yum-erlang_solutions": ">= 0.0.0",
      "dpkg_autostart": ">= 0.0.0",
      "logrotate": ">= 0.0.0"
    },
    "providing": {
      "rabbitmq::cluster": ">= 0.0.0",
      "rabbitmq::community_plugins": ">= 0.0.0",
      "rabbitmq": ">= 0.0.0",
      "rabbitmq::erlang_package": ">= 0.0.0",
      "rabbitmq::esl_erlang_package": ">= 0.0.0",
      "rabbitmq::management_ui": ">= 0.0.0",
      "rabbitmq::mgmt_console": ">= 0.0.0",
      "rabbitmq::plugin_management": ">= 0.0.0",
      "rabbitmq::plugins": ">= 0.0.0",
      "rabbitmq::policies": ">= 0.0.0",
      "rabbitmq::policy_management": ">= 0.0.0",
      "rabbitmq::systemd_limits": ">= 0.0.0",
      "rabbitmq::user_management": ">= 0.0.0",
      "rabbitmq::users": ">= 0.0.0",
      "rabbitmq::vhosts": ">= 0.0.0",
      "rabbitmq::virtualhost_management": ">= 0.0.0"
    },
    "recipes": {
      "rabbitmq": "Install and configure RabbitMQ",
      "rabbitmq::systemd_limits": "Sets up kernel limits (for example nofile) for RabbitMQ with systemd",
      "rabbitmq::cluster": "Set up RabbitMQ clustering.",
      "rabbitmq::management_ui": "Sets up RabbitMQ management plugin/UI",
      "rabbitmq::mgmt_console": "Deprecated, alias for rabbitmq::management_ui",
      "rabbitmq::plugins": "Manage plugins with node attributes",
      "rabbitmq::plugin_management": "Deprecated, alias for rabbitmq::plugins",
      "rabbitmq::vhosts": "Manage virtual hosts with node attributes",
      "rabbitmq::virtualhost_management": "Deprecated, alias for rabbitmq::vhosts",
      "rabbitmq::users": "Manage users with node attributes",
      "rabbitmq::user_management": "Deprecated, alias for rabbitmq::users",
      "rabbitmq::policies": "Manage policies with node attributes",
      "rabbitmq::policy_management": "Deprecated, alias for rabbitmq::policies",
      "rabbitmq::erlang_package": "Provisions Erlang with Team RabbitMQ packages",
      "rabbitmq::esl_erlang_package": "Alias for erlang::esl",
      "rabbitmq::community_plugins": ""
    },
    "version": "5.7.7",
    "source_url": "https://github.com/rabbitmq/chef-cookbook",
    "issues_url": "https://github.com/rabbitmq/chef-cookbook/issues",
    "privacy": false,
    "chef_versions": [
    ],
    "ohai_versions": [
    ],
    "gems": [
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

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

This method has no parameters.

Request

PUT /organizations/NAME/cookbook_artifacts/NAME/ID

The request body is similar to:

{
  "definitions": [
    {
      "name": "unicorn_config.rb",
      "checksum": "c92b659171552e896074caa58dada0c2",
      "path": "definitions/unicorn_config.rb",
      "specificity": "default"
    }
  ],
  "attributes": [],
  "files": [],
  "providers": [],
  "metadata": {
    "dependencies": {"ruby": [], "rubygems": []},
    "name": "unicorn",
    "maintainer_email": "ops@chef.io",
    "attributes": {},
    "license": "Apache 2.0",
    "suggestions": {},
    "platforms": {},
    "maintainer": "Chef Software, 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": [],
  "name": "unicorn",
  "identifier": "ba0dadcbca26710a521e0e3160cc5e20",
  "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_artifact_version"
}

where the checksum values must have already been uploaded to the Chef DSM using the sandbox endpoint. Once the user has uploaded a file with a particular checksum, redundant uploads aren’t 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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`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 in Chef Infra.

A cookbook defines a scenario and contains everything that’s required to support that scenario:

Recipes that specify which Chef Infra built-in resources to use, as well as the order in which they’re to be applied
Attribute values, which allow environment-based configurations such as dev or production.
Custom Resources for extending Chef Infra beyond the built-in resources.
Files and Templates for distributing information to systems.
Custom Ohai Plugins for extending system configuration collection beyond the Ohai defaults.
The metadata.rb file, which describes the cookbook itself and any dependencies it may have.

When a cookbook is uploaded, only files that are new or updated is included. This approach minimizes the amount of storage and time that’s required during the modify-upload-test cycle. Chef Infra Client uses a checksum and assigns a checksum to each file to keep track of which files have already been uploaded. These checksums are used in the cookbook version manifest, alongside the same records that store the file description (name, specificity), 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 returns the three latest versions, in descending order (newest to oldest). Use num_versions=all to return all cookbook versions. If num_versions isn't specified, a single cookbook version is returned. 0 is an invalid input (an empty array for the versions of each cookbook is returned).

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` returns the three latest versions, in descending order (newest to oldest). Use `num_versions=all` to return all cookbook versions. If `num_versions` isn't specified, a single cookbook version is returned. `0` is an invalid input (an empty array for the versions of each cookbook is returned).

Request

GET /organizations/NAME/cookbooks

Response

The response is similar to:

{
  "apache2": {
    "url": "https://localhost/cookbooks/apache2",
    "versions": [
      {"url": "https://localhost/cookbooks/apache2/5.1.0",
       "version": "5.1.0"},
      {"url": "https://localhost/cookbooks/apache2/4.2.0",
       "version": "4.2.0"}
    ]
  },
  "nginx": {
    "url": "https://localhost/cookbooks/nginx",
    "versions": [
      {"url": "https://localhost/cookbooks/nginx/1.0.0",
       "version": "1.0.0"},
      {"url": "https://localhost/cookbooks/nginx/0.3.0",
       "version": "0.3.0"}
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

/cookbooks/_latest

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

GET

The GET method is used to return a list of the most recent cookbook versions.

This method has no parameters.

Request

GET /organizations/NAME/cookbooks/_latest

Response

For example, if cookbooks foo and bar both exist on the Chef DSM and both with versions 0.1.0 and 0.2.0, the response is similar to:

{
  "foo": "https://localhost/cookbooks/foo/0.2.0",
  "bar": "https://localhost/cookbooks/bar/0.2.0"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/cookbooks/_recipes

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

GET

The GET method is used to return the names of all recipes in the most recent cookbook versions.

This method has no parameters.

Request

GET /organizations/NAME/cookbooks/_recipes

Response

The response is similar to:

{

}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/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.

Request

GET /organizations/NAME/cookbooks/NAME

Response

The response is similar to:

{
  "apache2": {
    "url": "https://localhost/cookbooks/apache2",
    "versions": [
      {"url": "https://localhost/cookbooks/apache2/5.1.0",
       "version": "5.1.0"},
      {"url": "https://localhost/cookbooks/apache2/4.2.0",
       "version": "4.2.0"}
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/cookbooks/NAME/version

A cookbook version represents a set of functionality that’s different from the cookbook on which it’s 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 DSM, and how Chef Infra 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/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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/NAME/cookbooks/NAME/VERSION

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

Response

The response is similar to:

{
  "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@chef.io",
    "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method is used to create or update a cookbook version. This method has no parameters.

Request

PUT /organizations/NAME/cookbooks/NAME/VERSION

with a request body similar to:

{
  "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@chef.io",
    "attributes": {},
    "license": "Apache 2.0",
    "suggestions": {},
    "platforms": {},
    "maintainer": "Chef Software, 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"
}

Response

This method has no response body.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`413`	Request entity too large. A request may not be larger than 1000000 bytes.

/data

Data bags store global variables as JSON data. Data bags are indexed for searching and can be loaded by a cookbook 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 DSM.

This method has no parameters.

Request

GET /organizations/NAME/data

Response

The response is similar to:

{
  "users": "https://chef.example/organizations/NAME/data/users",
  "applications": "https://chef.example/organizations/NAME/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 https://chef.example/organizations/NAME/data/foo is the path to the data bag.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

The POST method is used to create a new data bag on the Chef DSM. This method has no parameters.

Request

POST /organizations/NAME/data

with a request body that contains the key-value pair for the data bag and is similar to:

{
  "name": "users"
}

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

Response

The response is similar to:

{
   "uri": "https://organizations/NAME/data/users",
}

Response codes

Response Code	Description
`201`	Created. The object was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`409`	Conflict. A databag with that name already exists.
`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: DELETE, GET, and POST.

DELETE

The DELETE method is used to delete a data bag. This method has no parameters.

Request

DELETE /organizations/NAME/data/NAME

This method has no request body.

Response

The response is similar to:

{
  "name": "users",
  "json_class": "Chef::DataBag",
  "chef_type": "data_bag"
}

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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method returns a hash of all entries in the specified data bag. This method has no parameters.

Request

GET /organizations/NAME/data/NAME

Response

The response is similar to:

{
   "adam": "https://chef.example/organizations/NAME/data/users/adam"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

POST

The POST method is used to create a new data bag item. This method has no parameters.

Request

POST /organizations/NAME/data/NAME

with a request body similar to:

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

where id is required.

Response

This method has no response body.

Response codes

Response Code	Description
`201`	OK. The item was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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. 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 only structural requirement of a data bag item is that it must have an id:

{
  /* This is a supported comment style */
  // This style is also supported
  "id": "ITEM_NAME",
  "key": "value"
}

where

key and value are the key:value pair for each additional attribute within the data bag item
/* ... */ and // ... show two ways to add comments to 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/NAME/data/NAME/ITEM

Response

The response is similar to:

{
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/NAME/data/NAME/ITEM

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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

PUT /organizations/NAME/data/NAME/ITEM

with a request body similar to:

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

where id is required.

Response

The response is similar to:

{
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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 Infra. This mapping is accomplished by setting attributes and pinning cookbooks at the environment level. With environments, you can change cookbook configurations depending on the system’s designation. For example, by designating different staging and production environments, you can then define the correct URL of a database server for each environment. Environments also allow organizations to move new cookbook releases from staging to production with confidence by stepping releases through testing environments before entering production.

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/NAME/environments

Response

The response is similar to:

{
  "_default": "https://api.chef.io/organizations/org_name/environments/_default",
  "webserver": "https://api.chef.io/organizations/org_name/environments/webserver"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

The POST method is used to create a new environment. This method has no parameters.

Request

POST /organizations/NAME/environments

with a request body similar to:

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

Response

The response is similar to:

{ "uri": "https://localhost/environments/dev" }

Response codes

Response Code	Description
`201`	Created. The object was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't 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/_default

The /environments/_default endpoint has the following methods: GET.

GET

The GET method is used to get information about the _default environment on the Chef DSM. This method has no parameters.

Request

GET /organizations/NAME/environments/_default

Response

The response is similar to:

{
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/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/NAME/environments/NAME

Response

The response will return the JSON for the environment that was deleted, similar to:

{
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return the details for an environment as JSON. This method has no parameters.

Request

GET /organizations/NAME/environments/NAME

Response

The response is similar to:

{
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method updates the details of an environment on the Chef DSM. This method has no parameters.

Request

PUT /organizations/NAME/environments/NAME

with a request body that contains the updated JSON for the environment and is similar to:

{
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`413`	Request entity too large. A request may not be larger than 1000000 bytes.

/environments/NAME/cookbooks/NAME

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

GET

The GET method returns a hash of key-value pairs for the requested cookbook.

This method has the following parameters:

Parameter Description

Request

GET /organizations/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 is similar to:

{
  "apache2": {
    "url": "https://localhost/cookbooks/apache2",
    "versions": [
      {"url": "https://localhost/cookbooks/apache2/5.1.0",
       "version": "5.1.0"},
      {"url": "https://localhost/cookbooks/apache2/4.2.0",
       "version": "4.2.0"}
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/environments/NAME/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 are specified for an environment or when a cookbook specifies dependencies.

This method has no parameters.

Request

POST /organizations/NAME/environments/NAME/cookbook_versions

with a request body similar to:

{
  "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 returns 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.

The response is similar to:

{
  "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 aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`412`	Not allowed. A set of cookbooks and/or cookbook versions couldn't 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 doesn't 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

Request

GET /organizations/NAME/environments/NAME/cookbooks

Response

The response is similar to:

{
  "apache2": {
    "url": "https://localhost/cookbooks/apache2",
    "versions": [
      {"url": "https://localhost/cookbooks/apache2/5.1.0",
       "version": "5.1.0"},
      {"url": "https://localhost/cookbooks/apache2/4.2.0",
       "version": "4.2.0"}
    ]
  },
  "nginx": {
    "url": "https://localhost/cookbooks/nginx",
    "versions": [
      {"url": "https://localhost/cookbooks/nginx/1.0.0",
       "version": "1.0.0"},
      {"url": "https://localhost/cookbooks/nginx/0.3.0",
       "version": "0.3.0"}
    ]
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/NAME/environments/NAME/nodes

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/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 is similar to:

[
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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’s recommended (but not required) that GET /roles/NAME/environments/NAME be used instead of this endpoint.

This method has no parameters.

Request

GET /organizations/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 is similar to:

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

Chef Infra 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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/groups

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

GET

The GET method is used to get a list of groups on the Chef DSM for a single organization. This method has no parameters.

Request

GET /organizations/NAME/groups

Response

The response is similar to:

{
  "33a5c28a8efe11e195005fsaes25400298d3f": "https://url/for/group1",
  "admins": "https://url/for/groups/admins",
  "billing-admins": "https://url/for/billing-admins",
  "clients": "https://url/for/clients",
  "developers": "https://url/for/developers",
  "users": "https://url/for/groups/users"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

POST

The POST method is used to create a group on the Chef DSM for a single organization.

Request

POST /organizations/NAME/groups

with a request body similar to:

{
  "name": "group1",
  "groupname": "group1",
  "orgname": "test",
  "actors": []
  "clients": ["mynode"],
  "groups": ["admins"],
  "users": ["betina"]
}

Response

The response is similar to:

{
  "uri": "https://chef.example/organizations/test/groups/group1",
}

Response codes

Response Code	Description
`201`	OK. The group was created.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`409`	Conflict. The requested group already exists.

/groups/GROUP_NAME

The /groups/GROUP_NAME endpoint has the following methods: DELETE, GET and PUT.

DELETE

The DELETE method is used to remove a group from a single organization. This method has no parameters.

Request

DELETE /organizations/NAME/groups/GROUP_NAME

without a request body.

Response

The response is similar to:

{
}

Response codes

Response Code	Description
`200`	OK. The group was deleted.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to get lists of users and other groups that belong to a group. This method has no parameters.

Request

GET /organizations/NAME/groups/GROUP_NAME

Response

The response is similar to:

{
  "actors": [
    "pivotal",
    "grantmc"
  ],
  "users": [
    "pivotal",
    "grantmc"
  ],
  "clients": [

  ],
  "groups": [
    "000000000000ad94b5ddde157c070f0c"
  ],
  "orgname": "inbetweens",
  "name": "admins",
  "groupname": "admins"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method is used to update a group on a single organization. Updating the clients, groups and users memberships replaces the definitions for the group. GET the group and merge changes to create the desired member lists. This method has no parameters.

Request

PUT /organizations/NAME/groups/GROUP_NAME

with a request body similar to:

{
  "name": "group1",
  "groupname": "groupnew",
  "actors": {
    "clients": ["mynode","addme"],
    "groups": ["admins"],
    "users": ["betina"]
  }
}

Response

The response is similar to:

{
  "name": "group1",
  "groupname": "groupnew",
  "orgname": "test",
  "actors": {
    "clients": ["mynode","addme"],
    "groups": ["admins"],
    "users": ["betina"]
  }
}

Response codes

Response Code	Description
`201`	OK. The group was updated.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

/nodes

A node is any device—physical, virtual, cloud, network device, etc.—that’s under management by Chef Infra.

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 DSM. This method has no parameters.

Request

GET /organizations/NAME/nodes

Response

The response is similar to:

{
  "latte": "https://localhost/nodes/latte"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

The POST method is used to create a new node. This method has no parameters.

Request

POST /organizations/NAME/nodes

with a request body similar to:

{
  "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 is similar to:

{ "uri": "https://localhost/nodes/latte" }

Response codes

Response Code	Description
`201`	Created. The object was created.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't 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, HEAD and PUT.

DELETE

The DELETE method is used to delete a node. This method has no parameters.

Request

DELETE /organizations/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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return the details of a node as JSON. This method has no parameters.

Request

GET /organizations/NAME/nodes/NAME

Response

The response is similar to:

{
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

HEAD

The HEAD method is used to check the existence of a node. This method has no parameters.

Request

HEAD /organizations/NAME/nodes/NAME

Response

The method doesn’t return a body.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method is used to update a node. This method has no parameters.

Request

PUT /organizations/NAME/nodes/NAME

with a request body similar to:

{
  "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 returns the updated node.

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`413`	Request entity too large. A request may not be larger than 1000000 bytes.

/policies

The /policies endpoint has the following methods: GET.

GET

The GET method is used to get a list of policies (including policy revisions) from the Chef DSM. This method has no parameters.

Request

GET /organizations/NAME/policies

Response

The response groups policies by name and revision and is similar to:

{
  "aar": {
    "uri": "https://chef.example/organizations/org1/policies/aar",
    "revisions": {
      "37f9b658cdd1d9319bac8920581723efcc2014304b5f3827ee0779e10ffbdcc9": {
      },
      "95040c199302c85c9ccf1bcc6746968b820b1fa25d92477ea2ec5386cd58b9c5": {
      },
      "d81e80ae9bb9778e8c4b7652d29b11d2111e763a840d0cadb34b46a8b2ca4347": {
      }
    }
  },
  "jenkins": {
    "uri": "https://chef.example/organizations/org1/policies/jenkins",
    "revisions": {
      "613f803bdd035d574df7fa6da525b38df45a74ca82b38b79655efed8a189e073": {
      },
      "6fe753184c8946052d3231bb4212116df28d89a3a5f7ae52832ad408419dd5eb": {
      },
      "cc1a0801e75df1d1ea5b0d2c71ba7d31c539423b81478f65e6388b9ee415ad87": {
      }
    }
  }
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

/policy_groups

The /policy_groups endpoint has the following methods: GET.

Each node has a 1:many relationship with policy settings stored on the Chef DSM. This relationship is based on the policy group to which the node is associated, and then the policy settings assigned to that group:

A policy is typically named after the functional role a host performs, such as application server, chat server, or load balancer.
A policy group defines a set of hosts in a deployed units, typically mapped to organizational requirements such as dev, test, staging, and production, but can also be mapped to more detailed requirements as needed.

/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/NAME/principals/NAME

Response

For a user or client, the type value will vary. The response body returns an array of principals which allows for a client with the same name as a user. The response for a user or client is similar to:

{
  "Principals: [
    {
      "name": "normal_user",
      "type": "user",
      "public_key": "-----BEGIN PUBLIC KEY-----...",
      "authz_id": "eca5fdd45a8b4bacc04bbc6e37a340bes",
      "org_member":false
    }
  ]
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`404`	Not found. The requested object doesn't exist.

/required_recipe

The /required_recipe endpoint has the following method: GET.

GET

Use the GET method to view a recipe specified by a Chef DSM administrator as part of the Chef DSM configuration. This recipe will be run by all Chef Infra Clients that connect to the Chef DSM. The required_recipe feature is aimed at expert level practitioners delivering isolated configuration changes to target systems. The returned text is the content of a single recipe file.

This method has no parameters.

Request

GET /organizations/NAME/required_recipe

This method has no request body.

Response

The response is returned in plain text, not in JSON format. The response is similar to:

  "# My required recipe
   file '/tmp/build'
   package 'secret_sauce'
  "

Response codes

Response Code	Description
`200`	OK. The request was successful. Required recipe is enabled, a path to a recipe is defined, and a recipe exists at the path location.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not Found. The required recipe function isn't enabled.

/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 Infra 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/NAME/roles

Response

The response is similar to:

{
  "webserver": "https://chef.example/organizations/org1/roles/webserver"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

The POST method is used to create a new role on the Chef DSM. This method has no parameters.

Request

POST /organizations/NAME/roles

with a request body similar to:

{
  "name": "webserver",
  "default_attributes": {},
  "description": "A webserver",
  "env_run_lists": {
    "testenv": {
      "recipe[pegasus]"
    }
  },
  "run_list": [
    "recipe[unicorn]",
    "recipe[apache2]"
  ],
  "override_attributes": {}
}

Response

The response is similar to:

{ "uri": "https://chef.example/organizations/org1/roles/webserver" }

Response codes

Response Code	Description
`201`	OK. The request was successful.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't 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 DSM. This method has no parameters.

Request

DELETE /organizations/NAME/roles/NAME

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return the details for a role as JSON. This method has no parameters.

Request

GET /organizations/NAME/roles/NAME

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

PUT

The PUT method is used to update a role on the Chef DSM. This method has no parameters.

Request

PUT /organizations/NAME/roles/NAME

with a request body similar to:

{
  "name": "webserver",
  "default_attributes": {},
  "description": "A webserver",
  "env_run_lists": {},
  "default_attributes": {},
  "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/NAME/roles/NAME/environments

Response

The response is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/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 is similar to:

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

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't 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/NAME/sandboxes

with a request body similar to:

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

Response

The response is similar to:

{"uri":
 "https://api.chef.io/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 weren't properly uploaded. The payload doesn't contain a well-formed `checksums` parameter that's a hash containing a key for each checksum.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't 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 won’t require re-uploading the same data. This method has no parameters.

Request

PUT /organizations/NAME/sandboxes/ID

with a request body similar to:

{"is_completed":true}

Response

The response is similar to:

{
  "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 aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.
`413`	Request entity too large. A request may not be larger than 1000000 bytes.

/search

Search indexes allow queries to be made for any type of data that’s indexed by the Chef DSM, including data bags (and data bag items), environments, nodes, and roles. A defined query syntax is used to support search patterns like exact, wildcard, range, and fuzzy. A search is a full-text query that can be done from several locations, including from within a recipe, by using the search subcommand in knife, the search method in the Chef Infra Language, the search box in the Chef management console, and by using the /search or /search/INDEX endpoints in the Chef DSM API. The search engine is based on Elasticsearch and is run from the Chef DSM.

The /search endpoint allows nodes, roles, data bags, environments to be searched. This endpoint has the following methods: GET.

Note

At the end of every Chef Infra Client run, the node object is saved to the Chef DSM. From the Chef DSM, each node object is then added to the Apache Solr search index. This process is asynchronous. By default, node objects are committed to the search index every 60 seconds or for every 1000 node objects, whichever occurs first.

Note

This endpoint doesn’t have any ACL restrictions, which means it may be used by any user or client that’s able to make the request to the Chef DSM.

GET

The GET method is used to return a data structure that contains links to each available search index. By default, the role, node, client, and data bag indexes will always be available (where the data bag index is the name of the data bag on the Chef DSM). Search indexes may lag behind the most current data at any given time. If a situation occurs where data needs to be written and then immediately searched, an artificial delay (of at least 10 seconds) is recommended.

This method has no parameters.

Request

GET /organizations/NAME/search

This method has no request body.

Response

The response is similar to:

{
  "node": "https://chef.example/organizations/org1/search/node",
  "role": "https://chef.example/organizations/org1/search/role",
  "client": "https://chef.example/organizations/org1/search/client",
  "users": "https://chef.example/organizations/org1/search/users"
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

/search/INDEX

Use the /search/INDEX endpoint to access the search indexes on the Chef DSM. 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’s found in the JSON description of an indexable object on the Chef DSM (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’s 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 list of items on a Chef DSM. This option uses the same syntax as the `knife search` subcommand.
`rows`	The number of rows to be returned.
`start`	The row at which return results begin.

Request

GET /organizations/NAME/search/INDEX

Response

The response contains the total number of rows that match the request and for a node index search is similar to:

{
 "total": 1,
 "start": 0,
 "rows": [
    {
     "automatic": {"hardware_type": "laptop"},
     "chef_environment": "_default",
     "chef_type": "node",
     "default": {}
     "json_class": "Chef::Node",
     "name": "latte",
     "normal": {},
     "override": {"hardware_type": "laptop"},
     "run_list": ["recipe[unicorn]"]
    }
  ]
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

POST

A partial search query allows a search query to be made against specific attribute keys that are stored on the Chef DSM. A partial search query can search the same set of objects on the Chef DSM 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 Chef Infra Client processes the search results. The attributes to be returned by the partial search are specified in the request JSON body.

This method has the following parameters:

Parameter	Description
`q`	The search query used to identify a list of items on a Chef DSM. This option uses the same syntax as the `search` subcommand.
`rows`	The number of rows to be returned.
`start`	The row at which return results begin.

Request

POST /organizations/NAME/search

with a request body similar to:

{
  "name": [ "name" ],
  "ip": [ "ipaddress" ],
  "kernel_version": [ "kernel", "version" ]
}

Response

The response is similar to:

{
  "total":1,
  "start":0,
  "rows": [
    {
      "url": "https://chef.example/organization/org1/nodes/latte",
      "data": {
        "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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`413`	Request entity too large. A request may not be larger than 1000000 bytes.

/universe

Use the /universe endpoint to retrieve the known collection of cookbooks, and then use it with Berkshelf and Chef Supermarket.

The /universe endpoint has the following methods: GET.

GET

The GET method is used to retrieve the universe data. This method has no parameters. This method has no request body.

Request

GET /universe

Response

The response will return a json hash, with the name of each cookbook as a top-level key. Each cookbook will list each version, along with its location information and dependencies:

{
  "ffmpeg": {
    "0.1.0": {
      "location_path": "http://supermarket.chef.io/api/v1/cookbooks/ffmpeg/0.1.0/download",
      "location_type": "supermarket",
      "dependencies": {
        "git": ">= 0.0.0",
        "build-essential": ">= 0.0.0",
        "libvpx": "~> 0.1.1",
        "x264": "~> 0.1.1"
      }
    },
    "0.1.1": {
      "location_path": "http://supermarket.chef.io/api/v1/cookbooks/ffmpeg/0.1.1/download",
      "location_type": "supermarket",
      "dependencies": {
        "git": ">= 0.0.0",
        "build-essential": ">= 0.0.0",
        "libvpx": "~> 0.1.1",
        "x264": "~> 0.1.1"
      }
    }
  },
  "pssh": {
    "0.1.0": {
      "location_path": "http://supermarket.chef.io/api/v1/cookbooks/pssh.1.0/download",
      "location_type": "supermarket",
      "dependencies": {}
    }
  }
}

Response Code	Description
`200`	OK. The request was successful. One (or more) cookbooks and associated cookbook version information was returned.

/updated_since

The /updated_since endpoint ensures that replica instances of the Chef DSM are able to synchronize with the primary Chef DSM. /updated_since was part of the Chef Replication product. Chef Replication is no longer available as a product and the /updated_since endpoint is also deprecated. The expectation for almost all chef users is that use of the endpoint will return an http status of 404. The /organizations/NAME/updated_since endpoint has the following methods: GET.

Warning

This update is available after Chef replication is installed on the Chef DSM.

GET

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

Request

GET /organizations/NAME/updated_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 or client who made the request couldn't be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist or the function isn't implemented.

/users

A user may be associated with an organization. The /users endpoint has the following methods: GET and POST.

GET

The GET method is used to return an array of usernames for users associated with an organization. This method has no parameters.

Request

GET /organizations/NAME/users

This method has no request body.

Response

The response is similar to:

[
  { "user": { "username": "paperlatte" } }
]

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.

POST

The POST method is used to associate a user with an organization immediately. Superuser only. This method has no parameters.

Request

POST /organizations/NAME/users

with a request body similar to:

{
  "username": "paperlatte",
}

where username is the name of the user to be associated.

Response

No response block is returned.

Response codes

Response Code	Description
`201`	Created. The user was associated with the organization.
`400`	Bad request. The contents of the request aren't formatted correctly.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`409`	Conflict. The user is already associated.

/users/NAME

The /users/NAME endpoint has the following methods: DELETE, GET.

DELETE

The DELETE method is used to delete a user association with an organization. This method has no parameters.

Request

DELETE /organizations/NAME/users/NAME

Response

The response will return the end state of the user, similar to:

{
  "username": "paperlatte"
  "email": "latte",
  "display_name": "Ms. Latte",
  "first_name": "Paper",
  "last_name": "Latte",
  "public_key": "-----BEGIN PUBLIC KEY----- ... "
}

Response codes

Response Code	Description
`200`	OK. The request was successful. The user association was removed.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

GET

The GET method is used to return the details of a user as JSON. This method has no parameters.

Request

GET /organizations/NAME/users/NAME

Response

The response is similar to:

{
  "username": "paperlatte"
  "email": "latte",
  "display_name": "Ms. Latte",
  "first_name": "Paper",
  "last_name": "Latte",
  "public_key": "-----BEGIN PUBLIC KEY----- ... "
}

Response codes

Response Code	Description
`200`	OK. The request was successful.
`401`	Unauthorized. The user or client who made the request couldn't be authenticated. Verify the user/client name and that the correct key was used to sign the request.
`403`	Forbidden. The user who made the request isn't authorized to perform the action.
`404`	Not found. The requested object doesn't exist.

Examples

The following sections show examples of using the Chef DSM API.

Query for Users and Orgs

The following example shows how to query the Chef DSM API for a listing of organizations and users. The /organizations and /users endpoints may only be accessed by the pivotal user, which is a user account that’s created by Chef during the installation of the Chef DSM.

Run the following from a .chef directory that contains a pivotal.rb file:

require 'chef'
require 'chef/server_api'

Chef::Config.from_file('.chef/pivotal.rb')
rest = Chef::ServerAPI.new(Chef::Config[:chef_server_url])
orgs = rest.get('/organizations')

puts "\n=== Listing of organizations"
orgs.each do |org|
  puts org
end

puts "\n=== Listing of Users"
users = rest.get('/users')
users.each do |user|
  puts user
end

An example of a .chef/pivotal.rb file is shown below:

current_dir = File.dirname(__FILE__)
node_name 'pivotal'
chef_server_url 'https://192.0.2.0:443'
chef_server_root 'https://192.0.2.0:443'
client_key "#{current_dir}/pivotal.pem"

Note

The pivotal.pem file must exist in the specified location and the IP addresses must be correct for the Chef DSM.