Introduction

A cookbook is the fundamental unit of distribution in Chef. They are how you encapsulate all the different resources you need to automate your infrastructure, and they are the component that is easily sharable between different Chef users. Opscode maintains a public collection of cookbooks at cookbooks.opscode.com. This site contains all the cookbooks authored by Opscode, as well as many cookbooks from other members of the community.

All the cookbooks on the site are accessible through a REST API rooted at cookbooks.opscode.com/api/v1/. The endpoints and their HTTP methods are described below.

In most cases, using this API directly is unnecessary. Rather, you should use the knife cookbook site sub-commands or interact directly with the Cookbooks site. See Knife and Cookbook Site Help for more details.

API Endpoints

/cookbooks

HTTP METHODS

POST

Creates a new cookbook.

GET

Gets a listing of the available cookbooks. It is a good idea to use the optional parameters start and items to limit and paginate the results.

Parameters:

Example Request and Response

Each item in the array contains the name of the cookbook, the description, URI, and username of the maintainer of the cookbook. The total is the number of cookbooks on the site.

Response Codes:

• Returns "200 OK".

/cookbooks/{cookbook}

HTTP METHODS

DELETE

Deletes a cookbook. Not yet fully implemented.

GET

Gets a cookbook.

Parameters

None.

Example Request and Response

latest_version is the URI for the most recent version of the cookbook. external_url is an optional field that can be used by the cookbook maintainer to point to a related website. The versions array contains the URIs for all available versions of the cookbook.

Example Response for a Deprecated Cookbook

In this example, deprecated is set to true, indicating that the maintainer of the cookbook has deprecated it. In this case, another cookbook may be indicated in the replacement field. The replacement may also be "".

Response Codes:

• Returns 200 when the cookbook exists.
• Returns 404 when the cookbook does not exist. In this case, the response body will be:

/cookbooks/{cookbook}/versions/{version}

HTTP METHODS

GET

Gets a specific version of a cookbook.

Parameters

None.

Example Requests and Responses

The version is always in the form INT[_INT[Staging:_INT]] or "latest".

license is a string containing the name of the license under which the cookbook is distributed. It can contain anything the cookbook's maintainer chooses to put in it. file contains the link to the actual cookbook tarball.

Response Codes:

• Returns 200 when the cookbook exists.
• Returns 404 when the cookbook does not exist. In this case, the response body will be:

/search

HTTP METHODS

GET

Gets a listing of cookbooks whose names match a given string. It is a good idea to use the optional parameters start and items to limit and paginate the results.

Parameters

Examples and Responses

Items that are in the result set contain the search query in the cookbook_name or cookbook_description. Each item in the array contains the name of the cookbook, the description, URI, and username of the maintainer of the cookbook. The total is the number of cookbooks on the site.

Response Codes:

• Returns "200 OK".

Server API

Chef Concepts as UML