Optimal API for Dependency Resolution

The Cookbooks Site REST API makes it suboptimal for client programs performing dependency resolution, such as librarian-chef.

GET /api/v1/cookbooks/chef includes URLs for version resources, but does not include the version names. In order to get the version names, the client must guess the version names from the URLs of the version resources, or retrieve each version resource directly (GET /api/v1/cookbooks/chef/versions/0_99_0). This results in extra requests to find out the names of versions. GET /api/v1/cookbooks/chef/versions/0_99_0 does not include dependencies. In order to find out the dependencies, the client has to download and unpack the entire archive and open the metadata.json file. That’s 3 requests to find out the dependencies of the latest version of the chef cookbook.

The best solution is to include version names in cookbook index (/api/v1/cookbooks/chef) and version metadata (the contents of metadata.json) in the version resource (/api/v1/cookbooks/chef/versions/0_99_0), and even to include all of the full version resources as sub-documents of the cookbook index (possibly with a ?includes[versions][metadata]=true query-string parameter).

From COOK-474.