API супермаркета

[редактировать на GitHub]

API супермаркета используется для доступа к кулинарным книгам, инструментам и пользователям в Chef Supermarket. Все кулинарные книги, инструменты и пользователи в Supermarket доступны через RESTful API, обращаясь к supermarket.chef.io/api/v1/ через поддерживаемые конечные точки. В большинстве случаев, knife — это лучший способ взаимодействия с Supermarket; однако в некоторых случаях требуется прямой доступ к API Supermarket. .. note:: В общем случае, использование knife (и подкоманды knife supermarket ) для управления кулинарными книгами, расположенными на сайте Cookbooks, более эффективно, чем использование API Supermarket, и является рекомендуемым подходом для управления кулинарными книгами на этом сайте. Данный документ содержит информацию об API Supermarket в случае необходимости использования API.

Конечные точки

API Supermarket имеет следующие конечные точки.

/cookbooks

Кулинарная книга — это базовая единица конфигурации и распространения политики. Кулинарная книга определяет сценарий и содержит все необходимое для поддержки этого сценария:

Рецепты, определяющие используемые ресурсы и порядок их применения
Значения атрибутов
Распределение файлов
Шаблоны
Расширения Chef, такие как пользовательские ресурсы и библиотеки

Конечная точка /cookbooks имеет следующие методы: GET и POST.

POST

Метод POST используется для создания новой кулинарной книги.

Этот метод не имеет параметров.

Запрос

POST /api/v1/cookbooks/COOKBOOK_NAME

Ответ

Ответ похож на:

{
  "name": "apt",
  "maintainer": "opscode",
  "description": "Configures apt and apt services and LWRPs for managing apt repositories and preferences",
  "category": "Package Management",
  "latest_version": "http://supermarket.chef.io/api/v1/cookbooks/apt/versions/2_4_0",
  "external_url": "https://github.com/chef-cookbooks/apt",
  "average_rating": null,
  "created_at": "2009-10-25T23:48:48.000Z",
  "updated_at": "2014-05-15T17:45:14.000Z"
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Кулинарная книга была отправлена в API Supermarket.
`400`	Запрос не был выполнен успешно. Кулинарная книга не была отправлена в API Supermarket. Например: `{ "error_messages": ["You're not authorized to upload this cookbook."], "error_code": "UNAUTHORIZED" }`

GET

Метод GET используется для получения списка доступных кулинарных книг. Используйте параметры start и items для ограничения количества возвращаемых кулинарных книг. Используйте параметр order для изменения способа сортировки результатов. Используйте параметр user для фильтрации кулинарных книг по автору:

Параметр	Описание
`start`	Смещение в списке кулинарных книг, с которого начнется список.
`items`	Количество элементов, которые должны быть возвращены в результате запроса.
`order`	Токен, определяющий порядок сортировки результатов. Возможные значения: `recently_updated`, `recently_added`, `most_downloaded`, или `most_followed`.
`user`	Имя пользователя для фильтрации. Будут возвращены только кулинарные книги, поддерживаемые этим пользователем.

Запрос

GET /api/v1/cookbooks?start=START&items=ITEMS

или:

GET /api/v1/cookbooks?user=smith

Ответ

Ответ вернёт имя кулинарной книги, описание, URI, имя пользователя, поддерживающего кулинарную книгу. Кроме того, будет показано общее количество кулинарных книг в API Supermarket, а также (если указан start) точка, с которой начался список возвращаемых кулинарных книг:

{
   "total": 5234,
   "start": 20,
   "items":
      [
        {"cookbook_name": "apache",
         "cookbook_description": "installs apache.",
         "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/apache",
         "cookbook_maintainer": "john"
        },
        {"cookbook_name": "fail2ban",
         "cookbook_description": "installs fail2ban.",
         "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/fail2ban",
         "cookbook_maintainer": "jill"
        },
        {"cookbook_name": "mysql",
         "cookbook_description": null,
         "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/mysql",
         "cookbook_maintainer": "barry"
        },
        {"cookbook_name": "capistrano",
         "cookbook_description": null,
         "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/capistrano",
         "cookbook_maintainer": "pt"
        },
        {"cookbook_name": "ptapache",
         "cookbook_description": "an alternate apache recipe.",
         "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/ptapache",
         "cookbook_maintainer": "pt"
        }
      ]
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Одна или несколько кулинарных книг были возвращены в результате запроса.

/cookbooks/NAME

Конечная точка cookbooks/[NAME] позволяет получить доступ к определённой кулинарной книге. Эта конечная точка имеет следующие методы: DELETE и GET.

DELETE

Метод DELETE используется для удаления кулинарной книги.

Этот метод не имеет параметров.

Запрос

DELETE /api/v1/cookbooks/cookbook_name

Ответ

Ответ похож на:

{
  "name": "apt",
  "maintainer": "opscode",
  "description": "Configures apt and apt services and LWRPs for managing apt repositories and preferences",
  "category": "Package Management",
  "latest_version": "http://supermarket.chef.io/api/v1/cookbooks/apt/versions/2_4_0",
  "external_url": "https://github.com/chef-cookbooks/apt",
  "average_rating": null,
  "created_at": "2009-10-25T23:48:48.000Z",
  "updated_at": "2014-05-15T17:45:14.000Z"
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Кулинарная книга была удалена.
`400`	Запрос не был выполнен успешно. Запрашиваемая кулинарная книга не существует. Например: `{ "error_messages": ["Resource does not exist"], "error_code": "NOT_FOUND" }`
`403`	Неавторизован. Пользователь, который выполнил запрос, не имеет разрешения на выполнение действия. Пользователю не разрешено удалять кулинарную книгу. Например: `{}`

GET

Метод GET используется для получения данных о кулинарной книге.

Этот метод не имеет параметров.

Запрос

GET /api/v1/cookbooks/COOKBOOK_NAME

Ответ

Ответ вернёт данные о кулинарной книге, включая название, категорию, имя автора, URI последней версии и предыдущих версий, описание и т. д. Он также включает метрики о кулинарной книге, такие как количество загрузок и подписчиков:

{
  "name": "yum",
  "maintainer": "opscode",
  "description": "Configures various yum components on Red Hat-like systems",
  "category": "Package Management",
  "latest_version": "http://supermarket.chef.io/api/v1/cookbooks/yum/versions/3_2_2",
  "external_url": "https://github.com/chef-cookbooks/yum",
  "average_rating": null,
  "created_at": "2011-04-20T22:16:12.000Z",
  "updated_at": "2014-06-11T19:06:37.000Z",
  "deprecated": false,
  "versions": [
    "http://supermarket.chef.io/api/v1/cookbooks/yum/versions/3_2_2",
    "http://supermarket.chef.io/api/v1/cookbooks/yum/versions/3_2_0"
  ],
  "metrics": {
    "downloads": {
      "total": 8500
      "versions": {
        "3.2.0": 399,
        "3.2.2": 1
      }
   },
   "followers": 55
  }
}

Если кулинарная книга устарела, этот статус отмечается полем deprecated (равным true):

{
  "name": "apache",
  "category": "web servers",
  ...
  "deprecated": true,
  ...
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Запрашиваемая кулинарная книга существует.
`400`	Запрос не был выполнен успешно. Запрашиваемая кулинарная книга не существует. Например: `{ "error_messages": ["Resource does not exist"], "error_code": "NOT_FOUND" }`

/cookbooks/VERSION

Версия кулинарной книги всегда имеет вид x.y.z, где x, y и z — десятичные числа, используемые для представления основных (x), второстепенных (y) и исправленных (z) версий. Разрешена и двухчастная версия (x.y). При передаче версии кулинарной книги с помощью этого метода в качестве разделителя между версиями следует использовать символ подчёркивания («_»). Например, кулинарная книга с версией 1.0.1 будет представлена как 1_0_1.

Конечная точка /cookbooks/[VERSION] имеет следующие методы: DELETE и GET.

DELETE

Метод DELETE используется для удаления версии кулинарной книги.

Этот метод не имеет параметров.

Запрос

DELETE /api/v1/cookbooks/cookbook_name/versions/version

Ответ

Ответ похож на:

{
  "license": "Apache 2.0",
  "tarball_file_size": 18553,
  "version": "2.4.0",
  "average_rating": null,
  "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/apt",
  "file": "http://supermarket.chef.io/api/v1/cookbooks/apt/versions/2_4_0/download",
  "dependencies": {},
  "platforms": {
    "debian": ">= 0.0.0",
    "ubuntu": ">= 0.0.0"
  }
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Версия кулинарной книги была удалена.
`400`	Запрос не был выполнен успешно. Запрашиваемая кулинарная книга или версия кулинарной книги не существует. Например: `{ "error_messages": ["Resource does not exist"], "error_code": "NOT_FOUND" }`
`403`	Неавторизован. Пользователь, который выполнил запрос, не имеет разрешения на выполнение действия. Пользователю не разрешено удалять версию кулинарной книги. Например: `{}`

GET

Метод GET используется для получения определённой версии кулинарной книги. Используйте latest для получения последней версии кулинарной книги.

Этот метод не имеет параметров.

Запрос

GET /api/v1/cookbooks/COOKBOOK_NAME/versions/latest

или:

GET /api/v1/cookbooks/COOKBOOK_NAME/versions/VERSION

Ответ

Ответ вернёт данные о версии кулинарной книги, включая лицензию, последнюю обновление, версию, URI, дату создания кулинарной книги, путь к файлу кулинарной книги tar.gz, зависимости и поддерживаемые платформы и т. д.:

{
  "license": "Apache 2.0",
  "tarball_file_size": 18553,
  "version": "2.4.0",
  "average_rating": null,
  "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/apt",
  "file": "http://supermarket.chef.io/api/v1/cookbooks/apt/versions/2_4_0/download",
  "dependencies": {},
  "platforms": {
    "debian": ">= 0.0.0",
    "ubuntu": ">= 0.0.0"
  }
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Запрашиваемая кулинарная книга существует.
`400`	Запрос не был выполнен успешно. Запрашиваемая кулинарная книга не существует. Например: `{ "error_messages": ["Resource does not exist"], "error_code": "NOT_FOUND" }`

/search

Поиск выполняет размытый поиск по ключевым словам в названиях кулинарных книг, описаниях и именах пользователей, поддерживающих кулинарные книги.

Конечная точка /search имеет следующие методы: GET.

GET

Метод GET используется для получения списка кулинарных книг, соответствующих запросу поиска. Используйте параметры start и items для ограничения количества возвращаемых кулинарных книг:

Параметр	Описание
`q`	Запрос поиска, используемый для идентификации списка элементов на сервере Chef Infra. Этот параметр использует ту же синтаксическую структуру, что и подкоманда `search`.
`start`	Строка, с которой начнутся результаты возврата.
`items`	Количество строк, которые должны быть возвращены.

Запрос

GET /api/v1/search?q=SEARCH_QUERY

или:

GET /api/v1/search?q=SEARCH_QUERY&start=START&items=ITEMS

Ответ

Ответ вернёт список кулинарных книг по имени и описанию, а также список кулинарных книг, соответствующих запросу поиска. Каждый возвращаемый набор данных будет включать имя кулинарной книги, описание, URI и имя лица, которое поддерживает кулинарную книгу. Кроме того, будет показано общее количество кулинарных книг в Supermarket API (если start указано), а также точка начала списка возвращаемых кулинарных книг:

{
  "total": 2,
  "start": 0,
  "items": [
    {
      "cookbook_name": "apache",
      "cookbook_description": "installs a web server.",
      "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/apache",
      "cookbook_maintainer": "jtimberman"
    },
    {
      "cookbook_name": "webserver",
      "cookbook_description": "installs apache.",
      "cookbook": "http://supermarket.chef.io/api/v1/cookbooks/webserver",
      "cookbook_maintainer": "raxmus"
    }
  ]
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Одна или несколько кулинарных книг были возвращены в результате запроса поиска.

/tools

Конечная точка tools позволяет получить доступ к инструментам Chef Supermarket. Эта конечная точка имеет следующие методы: GET.

GET

Метод GET используется для получения списка доступных инструментов. Используйте параметры start и items для установления ограничений на количество возвращаемых инструментов. Используйте параметр order для изменения способа сортировки результатов.

Параметр	Описание
`start`	Смещение в списке инструментов, с которого начнётся список инструментов.
`items`	Количество элементов, которые должны быть возвращены в результате запроса.
`order`	Токен, определяющий способ упорядочения результатов. Возможные значения: `recently_added`.

Запрос

GET /api/v1/tools?start=START&items=ITEMS

или:

GET /api/v1/tools?order=recently_added

Ответ

Ответ вернёт имя инструмента, тип, описание, владельца, URL источника и URI. Кроме того, будет показано общее количество инструментов в Supermarket API (если start указано), а также точка начала списка возвращаемых инструментов:

{
  "start": 0,
  "total": 56,
  "items": [
    {
      "tool_name": "Berkflow",
      "tool_type": "chef_tool",
      "tool_source_url": "https://github.com/reset/berkflow",
      "tool_description": "A Cookbook-Centric Deployment workflow tool",
      "tool_owner": "reset",
      "tool": "https://supermarket.chef.io/api/v1/tools/berkflow"
    },
    {
      "tool_name": "Berkshelf",
      "tool_type": "chef_tool",
      "tool_source_url": "https://github.com/berkshelf/berkshelf",
      "tool_description": "A Chef Cookbook manager",
      "tool_owner": "reset",
      "tool": "https://supermarket.chef.io/api/v1/tools/berkshelf"
    },
    {
      "tool_name": "Berkshelf-API",
      "tool_type": "chef_tool",
      "tool_source_url": "https://github.com/berkshelf/berkshelf-api",
      "tool_description": "Berkshelf dependency API server",
      "tool_owner": "reset",
      "tool": "https://supermarket.chef.io/api/v1/tools/berkshelf-api"
    }
  ]
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Один или несколько инструментов были возвращены.

/tools-search

Конечная точка tools позволяет выполнить поиск инструментов Chef Supermarket. Эта конечная точка имеет следующие методы: GET.

GET

Метод GET используется для получения списка инструментов, соответствующих запросу поиска. Используйте параметры start и items для установления ограничений на количество возвращаемых инструментов:

Параметр	Описание
`q`	Запрос поиска, используемый для определения списка элементов на сервере Chef Infra. Этот параметр использует ту же синтаксическую конструкцию, что и подкоманда `search`.
`start`	Строка, с которой начинаются возвращаемые результаты.
`items`	Количество строк, которые должны быть возвращены.

Запрос

GET /api/v1/tools-search?q=SEARCH_QUERY

или:

GET /api/v1/tools-search?q=SEARCH_QUERY&start=START&items=ITEMS

Ответ

Ответ вернёт список инструментов, соответствующих запросу поиска. Каждый возвращаемый набор данных будет включать имя инструмента, тип, описание, владельца, URL источника и URI. Кроме того, будет показано общее количество инструментов, соответствующих запросу в Supermarket API (если start указано), а также точка начала списка возвращаемых инструментов:

{
  "start": 0,
  "total": 1,
  "items": [
    {
      "tool_name": "knife-rhn",
      "tool_type": "knife_plugin",
      "tool_source_url": "https://github.com/bflad/knife-rhn",
      "tool_description": "Knife Plugin for Red Hat Network (RHN)",
      "tool_owner": "bflad",
      "tool": "https://supermarket.chef.io/api/v1/tools/knife-rhn"
    }
  ]
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Один или несколько инструментов были возвращены в результате запроса поиска.

/tools/SLUG

Конечная точка tools/[SLUG] позволяет получить доступ к конкретному инструменту. Эта конечная точка имеет следующие методы: GET.

GET

Метод GET используется для получения подробной информации об инструменте.

Этот метод не имеет параметров.

Запрос

GET /api/v1/tools/TOOL_SLUG

Ответ

Ответ вернёт подробную информацию об инструменте, включая имя инструмента, тип, описание, владельца, URL источника и инструкции по установке в формате Markdown:

{
  "name": "Berkshelf",
  "slug": "berkshelf",
  "type": "chef_tool",
  "source_url": "https://github.com/berkshelf/berkshelf",
  "description": "A Chef Cookbook manager",
  "instructions": "# Berkshelf\r\n[![Gem Version](https://img.shields.io/gem/v/berkshelf.svg)][gem]\r\n[![Build Status](https://img.shields.io/travis/berkshelf/berkshelf.svg)][travis]\r\n\r\n[gem]: https://rubygems.org/gems/berkshelf\r\n[travis]: https://travis-ci.org/berkshelf/berkshelf\r\n\r\nManage a Cookbook or an Application's Cookbook dependencies\r\n\r\n## Installation\r\n\r\nBerkshelf is now included as part of the [Chef-DK](http://chef.io/downloads/chef-dk). This is fastest, easiest, and the recommended installation method for getting up and running with Berkshelf.\r\n\r\n> note: You may need to uninstall the Berkshelf gem especially if you are using a Ruby version manager you may need to uninstall all Berkshelf gems from each Ruby installation.\r\n\r\n### From Rubygems\r\n\r\nIf you are a developer or you prefer to install from Rubygems, we've got you covered.\r\n\r\nAdd Berkshelf to your repository's `Gemfile`:\r\n\r\n```ruby\r\ngem 'berkshelf'\r\n```\r\n\r\nOr run it as a standalone:\r\n\r\n    gem install berkshelf\r\n\r\n## Usage\r\n\r\nSee [berkshelf.com](http://berkshelf.com) for up-to-date usage instructions.\r\n\r\n## Supported Platforms\r\n\r\nBerkshelf is tested on Ruby 1.9.3, 2.0, and 2.1.\r\n\r\nRuby 1.9 mode is required on all interpreters.\r\n\r\nRuby 1.9.1 and 1.9.2 are not officially supported. If you encounter problems, please upgrade to Ruby 2.0 or 1.9.3.\r\n\r\n## Configuration\r\n\r\nBerkshelf will search in specific locations for a configuration file. In order:\r\n\r\n    $PWD/.berkshelf/config.json\r\n    $PWD/berkshelf/config.json\r\n    $PWD/berkshelf-config.json\r\n    $PWD/config.json\r\n    ~/.berkshelf/config.json\r\n\r\nYou are encouraged to keep project-specific configuration in the `$PWD/.berkshelf` directory. A default configuration file is generated for you, but you can update the values to suit your needs.\r\n\r\n## Shell Completion\r\n\r\n- [Bash](https://github.com/berkshelf/berkshelf-bash-plugin)\r\n- [ZSH](https://github.com/berkshelf/berkshelf-zsh-plugin)\r\n\r\n## Plugins\r\n\r\nPlease see [Plugins page](https://github.com/berkshelf/berkshelf/blob/master/PLUGINS.md) for more information.\r\n\r\n## Getting Help\r\n\r\n* If you have an issue: report it on the [issue tracker](https://github.com/berkshelf/berkshelf/issues)\r\n* If you have a question: visit the #general or #berkshelf channel in the Chef Community Slack (http://community-slack.chef.io/)\r\n\r\n## Authors\r\n\r\n[The Berkshelf Core Team](https://github.com/berkshelf/berkshelf/wiki/Core-Team)\r\n\r\nThank you to all of our [Contributors](https://github.com/berkshelf/berkshelf/graphs/contributors), testers, and users.\r\n\r\nIf you'd like to contribute, please see our [contribution guidelines](https://github.com/berkshelf/berkshelf/blob/master/CONTRIBUTING.md) first.\r\n",
  "owner": "reset"
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Запрашиваемый инструмент существует.
`400`	Запрос не был выполнен успешно. Запрашиваемый инструмент не существует. Например: `{ "error_messages": ["Resource does not exist"], "error_code": "NOT_FOUND" }`

/universe

Вселенная — это известное собрание кулинарных книг, которые были загружены в Chef Supermarket. Вселенная — это данные JSON, организованные по кулинарным книгам, затем по версиям кулинарных книг и по графу зависимостей, в котором перечислены все зависимости, которые может иметь версия кулинарной книги от других кулинарных книг или версий кулинарных книг.

Используйте конечную точку /universe для получения известного набора кулинарных книг, а затем используйте его с Berkshelf.

Конечная точка /universe имеет следующие методы: GET.

GET

Метод GET используется для получения данных вселенной.

Этот метод не имеет параметров.

Запрос

GET /universe

Ответ

Ответ вернёт вложенный хеш, где имя каждой кулинарной книги будет являться ключом верхнего уровня. Каждая кулинарная книга будет перечислять каждую версию вместе с информацией о расположении и зависимостях:

{
  "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": {},
    }
  }
}

Код ответа	Описание
`200`	OK. Запрос был выполнен успешно. Были возвращены сведения об одной (или нескольких) кулинарных книгах и связанных с ними версиях кулинарных книг.

/users/USERNAME

Конечная точка users/[USERNAME] позволяет получить доступ к конкретному пользователю Chef Supermarket. Эта конечная точка имеет следующие методы: GET.

GET

Метод GET используется для получения подробной информации о пользователе.

Этот метод не имеет параметров.

Запрос

GET /api/v1/users/USERNAME

Ответ

Ответ вернёт подробную информацию о пользователе, включая имя, имя пользователя Chef, связанные данные учётной записи и список кулинарных книг и инструментов, связанных с пользователем. Кулинарные книги сгруппированы в три категории: те, которые принадлежат этому пользователю, в которых этот пользователь участвовал и которые он отслеживает.

{
  "username": "stevedanno",
  "name": "Steve Danno",
  "company": "Chef Software, Inc",
  "github": [
    "stevedanno"
  ],
  "twitter": "stevedanno",
  "irc": "stevedanno",
  "cookbooks": {
    "owns": {
      "bacon": "https://supermarket.chef.io/api/v1/cookbooks/bacon"
      "chef-sugar": "https://supermarket.chef.io/api/v1/cookbooks/chef-sugar"
    },
    "collaborates": {
      "build-essential": "https://supermarket.chef.io/api/v1/cookbooks/build-essential"
      "jenkins": "https://supermarket.chef.io/api/v1/cookbooks/jenkin"
    },
    "follows": {
      "bacon": "https://supermarket.chef.io/api/v1/cookbooks/bacon"
      "chef-sugar": "https://supermarket.chef.io/api/v1/cookbooks/chef-sugar"
    }
  },
  "tools": {
    "owns": {
      "bacon_tool": "https://supermarket.chef.io/api/v1/tools/bacon_tool"
    }
  }
}

© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs.chef.io/supermarket_api/