RubyGems.org API - RubyGems 指南

指南

在命令行中使用多因素身份验证

有关通过 HTTP 与 RubyGems.org 交互的详细信息。

注意：API 正在开发中，可以利用您的帮助！ RubyGems 本身和 RubyGems gem 使用 API 来推送 gems、添加所有者等等。

API 授权：如何使用 RubyGems.org 进行身份验证
速率限制
Gem 方法：查询或创建要托管的 gems
Gem 版本方法：查询有关特定 gem 版本的信息
Gem 下载方法：查询下载统计信息
所有者方法：管理 gems 的所有者
Webhook 方法：管理推送 gems 时的通知
活动方法：查询有关网站范围活动的信息
其他方法：与网站的其他各种交互

API 授权

某些 API 调用需要授权标头。要创建或查看现有的 API 密钥，请在登录 RubyGems.org 后点击您的用户名，然后点击“设置”，再点击“API 密钥”。以下是如何使用 API 密钥的示例

$ curl -H 'Authorization:YOUR_API_KEY' \
  https://rubygems.org.cn/api/v1/some_api_call.json

如果您使用的是多因素身份验证，则需要在 OTP 标头中提供一次性密码。以下是如何使用您的 API 密钥和 OTP 的示例

$ curl -H 'Authorization:YOUR_API_KEY' \
       -H 'OTP:YOUR_ONE_TIME_PASSCODE' \
  https://rubygems.org.cn/api/v1/some_api_call.json

Ruby 库

您也可以使用 Ruby 与 RubyGems.org 交互。

The gems 客户端为所有列出的资源提供了 Ruby 接口。该库有完整文档，其中包括 README 中的一些基本用法示例。您可以使用以下命令安装该库

gem install gems

速率限制

请参阅 RubyGems.org 速率限制

Gem 方法

GET - `/api/v1/gems/[GEM NAME].(json|yaml)`

返回有关给定 gem 的一些基本信息。以下是以 JSON 格式显示的 gem“rails”的示例响应

$ curl https://rubygems.org.cn/api/v1/gems/rails.json

{
  "name": "rails",
  "downloads": 7528417,
  "version": "3.2.1",
  "version_downloads": 47602,
  "authors": "David Heinemeier Hansson",
  "info": "Ruby on Rails is a full-stack web framework optimized for programmer
          happiness and sustainable productivity. It encourages beautiful code
          by favoring convention over configuration.",
  "project_uri": "https://rubygems.org.cn/gems/rails",
  "gem_uri": "https://rubygems.org.cn/gems/rails-3.2.1.gem",
  "homepage_uri": "http://www.rubyonrails.org",
  "wiki_uri": "http://wiki.rubyonrails.org",
  "documentation_uri": "https://api.rubyonrails.net.cn",
  "mailing_list_uri": "http://groups.google.com/group/rubyonrails-talk",
  "source_code_uri": "http://github.com/rails/rails",
  "bug_tracker_uri": "http://github.com/rails/rails/issues",
  "dependencies": {
    "development": [],
    "runtime": [
      {
        "name": "actionmailer",
        "requirements":"= 3.2.1"
      },
      {
        "name": "actionpack",
        "requirements": "= 3.2.1"
      },
      {
        "name": "activerecord",
        "requirements": "= 3.2.1"
      },
      {
        "name": "activeresource",
        "requirements": "= 3.2.1"
      },
      {
        "name": "activesupport",
        "requirements": "= 3.2.1"
      },
      {
        "name": "bundler",
        "requirements": "~> 1.0"
      },
      {
        "name": "railties",
        "requirements": "= 3.2.1"
      }
    ]
  }
}
}

GET - `/api/v1/search.(json|yaml)?query=[YOUR QUERY]`

向 RubyGems.org 提交对活动 gem 的搜索，就像在网站上进行搜索查询一样。返回一个包含匹配 gem 的 JSON 或 YAML 表示形式的数组。

$ curl 'https://rubygems.org.cn/api/v1/search.json?query=cucumber'

$ curl 'https://rubygems.org.cn/api/v1/search.yaml?query=cucumber'

结果是分页的，因此 API 调用将只返回前 30 个匹配的 gem。要获取后续结果，请使用 page 查询参数，直到收到空响应。

$ curl 'https://rubygems.org.cn/api/v1/search.json?query=cucumber&page=2'

GET - `/api/v1/gems.(json|yaml)`

列出您拥有的所有 gem。返回一个包含您拥有的 gem 的 JSON 或 YAML 表示形式的数组。

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
          https://rubygems.org.cn/api/v1/gems.json

POST - `/api/v1/gems`

向 RubyGems.org 提交一个 gem。必须在请求正文中发布一个已构建的 RubyGem。

$ curl --data-binary @gemcutter-0.2.1.gem \
       -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       https://rubygems.org.cn/api/v1/gems

Successfully registered gem: gemcutter (0.2.1)

DELETE - `/api/v1/gems/yank`

从 RubyGems.org 的索引中删除一个 gem。平台是可选的。

$ curl -X DELETE -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -d 'gem_name=bills' -d 'version=0.0.1' \
       -d 'platform=x86-darwin-10' \
       https://rubygems.org.cn/api/v1/gems/yank

Successfully yanked gem: bills (0.0.1)

GET - `/api/v1/gems/[GEM NAME]/reverse_dependencies.json`

列出指定 gem 的依赖项。这是所有其最新版本依赖于特定 gem 的依赖项。返回一个包含依赖 gem 名称的数组。

$ curl https://rubygems.org.cn/api/v1/gems/shoulda/reverse_dependencies.json

[
  "jeweler",
  "rubigen",
  "verhoeff",
  "vanilla",
  "soup",
  ...
]

Gem 版本方法

GET - `/api/v1/versions/[GEM NAME].(json|yaml)`

返回一个包含 gem 版本详细信息的数组，如下所示

$ curl https://rubygems.org.cn/api/v1/versions/coulda.json

[
  {
    "authors" : "Evan David Light",
    "built_at" : "2011-08-08T04:00:00.000Z",
    "created_at" : "2011-08-08T21:23:40.254Z",
    "description" : "Behaviour Driven Development derived from Cucumber but as an internal DSL with methods for reuse",
    "downloads_count" : 2224,
    "number" : "0.7.1",
    "summary" : "Test::Unit-based acceptance testing DSL",
    "platform" : "ruby",
    "ruby_version" : nil,
    "prerelease" : false,
    "licenses" : nil,
    "requirements" : nil,
    "sha" : "777c3a7ed83e44198b0a624976ec99822eb6f4a44bf1513eafbc7c13997cd86c"
  }
]

GET - `/api/v1/versions/[GEM NAME]/latest.json`

返回一个包含特定 gem 的最新版本的对象。

$ curl https://rubygems.org.cn/api/v1/versions/rails/latest.json

{
  "version": "4.2.1"
}

GET - `/api/v1/timeframe_versions.json`

返回一个包含在时间戳参数指定的时间范围内创建的 gem 版本的数组。

需要一个名为 from 的 iso8601 时间戳参数。这是您想要开始查询的时间。您可以包含一个名为 to 的 iso8601 时间戳参数。如果存在，则只返回在 from 和 to 之间创建的版本。如果未给出 to，则将返回在 from 和当前时间之间创建的所有版本。

注意：您使用 from 和 to 指定的时间范围不能超过 7 天。

结果是分页的，因此 API 调用将只返回时间范围内的前 30 个版本。要获取后续结果，请使用 page 查询参数，直到收到空响应。

示例响应

$ curl 'https://rubygems.org.cn/api/v1/timeframe_versions.json?from=2019-01-18T21:24:29Z&to=2019-01-18T21:24:31Z

[{
  "name": "rails",
  "downloads": 158094751,
  "version": "6.0.0.beta1",
  "version_downloads": 677,
  "platform": "ruby",
  "authors": "David Heinemeier Hansson",
  "info": "Ruby on Rails is a full-stack web framework optimized for programmer happiness and sustainable productivity. It encourages beautiful code by favoring convention over configuration.",
  "licenses": ["MIT"],
  "metadata": {},
  "sha": "f70cc2e606eafd6c3fd1d7e15f015d6a3e5626d34724ba5c0114922a8eb864b8",
  "project_uri": "http://localhost/gems/rails",
  "gem_uri": "http://localhost/gems/rails-6.0.0.beta1.gem",
  "homepage_uri": "https://rubyonrails.net.cn",
  "wiki_uri": "",
  "documentation_uri": "https://api.rubyonrails.net.cn",
  "mailing_list_uri": "http://groups.google.com/group/rubyonrails-talk",
  "source_code_uri": "http://github.com/rails/rails",
  "bug_tracker_uri": "http://github.com/rails/rails/issues",
  "changelog_uri": null,
  "dependencies": {
    "development": [],
    "runtime": [{
      "name": "actioncable",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "actionmailbox",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "actionmailer",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "actionpack",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "actiontext",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "actionview",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "activejob",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "activemodel",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "activerecord",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "activestorage",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "activesupport",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "bundler",
      "requirements": "\u003e= 1.3.0"
    }, {
      "name": "railties",
      "requirements": "= 6.0.0.beta1"
    }, {
      "name": "sprockets-rails",
      "requirements": "\u003e= 2.0.0"
    }]
  },
  "built_at": "2019-01-18T00:00:00.000Z",
  "created_at": "2019-01-18T21:24:30.197Z",
  "description": "Ruby on Rails is a full-stack web framework optimized for programmer happiness and sustainable productivity. It encourages beautiful code by favoring convention over configuration.",
  "downloads_count": 677,
  "number": "6.0.0.beta1",
  "summary": "Full-stack web application framework.",
  "rubygems_version": "\u003e= 1.8.11",
  "ruby_version": "\u003e= 2.5.0",
  "prerelease": true,
  "requirements": []
}]

Gem 下载方法

GET - `/api/v1/downloads.(json|yaml)`

返回一个包含 RubyGems 上总下载次数的对象。

$ curl https://rubygems.org.cn/api/v1/downloads.json

{
  "total": 461672727
}

GET - `/api/v1/downloads/[GEM NAME]-[GEM VERSION].(json|yaml)`

返回一个包含特定 gem 的总下载次数以及指定版本的总下载次数的对象。

$ curl https://rubygems.org.cn/api/v1/downloads/rails_admin-0.0.0.json

{
  "version_downloads": 3142,
  "total_downloads": 3142
}

所有者方法

GET - `/api/v1/owners/[USER HANDLE|USER ID]/gems.(json|yaml)`

查看用户的全部 gem。这些是用户可以推送到的所有 gem。所有者 gem 列表可以通过用户句柄或用户 ID 请求。

$ curl https://rubygems.org.cn/api/v1/owners/qrush/gems.json

[
  {
    "name": "factory_bot",
...
  },
...
]

GET - `/api/v1/gems/[GEM NAME]/owners.(json|yaml)`

查看 gem 的所有所有者。这些用户都可以向该 gem 推送。

$ curl https://rubygems.org.cn/api/v1/gems/gemcutter/owners.json

[
  {
    "email": "[email protected]"
  },
  {
    "email": "[email protected]"
  }
]

POST - `/api/v1/gems/[GEM NAME]/owners`

将所有者添加到您拥有的 RubyGem，赋予该用户管理它的权限。

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F '[email protected]' \
       https://rubygems.org.cn/api/v1/gems/gemcutter/owners

Owner added successfully.

DELETE - `/api/v1/gems/[GEM NAME]/owners`

删除用户管理您拥有的 RubyGem 的权限。

$ curl -X DELETE -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
        -d "[email protected]" \
        https://rubygems.org.cn/api/v1/gems/gemcutter/owners

Owner removed successfully.

个人资料方法

GET - `/api/v1/profiles/[USER HANDLE|USER ID].(json|yaml)`

查看用户的基本用户信息。

$ curl https://rubygems.org.cn/api/v1/profiles/qrush

[
  {
    "id": 1,
    "handle": "qrush"
  }
]

$ curl https://rubygems.org.cn/api/v1/profiles/1

[
  {
    "id": 1,
    "handle": "qrush"
  }
]

GET - `/api/v1/profile/me.(json|yaml)`

查看您帐户的基本用户信息，包括多因素身份验证状态。需要传递用户名和密码。

$ curl -u "[email protected]:schwwwwing" \
       https://rubygems.org.cn/api/v1/profile/me

[
  {
    "id": 1,
    "handle": "qrush",
    "mfa": "enabled"
  }
]

WebHook 方法

GET - `/api/v1/web_hooks.(json|yaml)`

列出您帐户下注册的 webhook。

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       https://rubygems.org.cn/api/v1/web_hooks.json

{
  "all gems": [
    {
      "url": "http://gemwhisperer.heroku.com",
      "failure_count": 1
    }
  ],
  "rails": [
    {
      "url": "http://example.com",
      "failure_count": 0
    }
  ]
}

POST - `/api/v1/web_hooks`

创建 webhook。需要两个参数：gem_name 和 url。将 * 指定为 gem_name 参数以将钩子全局应用于所有 gem。

$ curl -X POST -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'gem_name=rails' -F 'url=http://example.com' \
       https://rubygems.org.cn/api/v1/web_hooks

Successfully created webhook for rails to http://example.com

$ curl -X POST -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'gem_name=*' -F 'url=http://example.com' \
       https://rubygems.org.cn/api/v1/web_hooks

Successfully created webhook for all gems to http://example.com

DELETE - `/api/v1/web_hooks/remove`

删除 webhook。需要两个参数：gem_name 和 url。将 * 指定为 gem_name 参数以将钩子全局应用于所有 gem。

$ curl -X DELETE -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -d 'gem_name=rails' -d 'url=http://example.com' \
       https://rubygems.org.cn/api/v1/web_hooks/remove

Successfully removed webhook for rails to http://example.com

$ curl -X DELETE -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -d 'gem_name=*' -d 'url=http://example.com' \
       https://rubygems.org.cn/api/v1/web_hooks/remove

Successfully removed webhook for all gems to http://example.com

POST - `/api/v1/web_hooks/fire`

测试触发 webhook。这可用于随时测试端点，例如在开发应用程序时。需要两个参数：gem_name 和 url。将 * 指定为 gem_name 参数以将钩子全局应用于所有 gem。

每个触发的 webhook 都会包含一个 Authorization 头部，以便您可以确定请求来自 RubyGems.org。该头部的值是 gem 名称、gem 版本和您的 API 密钥的 SHA2 哈希连接。

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'gem_name=rails' -F 'url=http://example.com' \
       https://rubygems.org.cn/api/v1/web_hooks/fire

Successfully deployed webhook for rails to http://example.com

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'gem_name=*' -F 'url=http://example.com' \
       https://rubygems.org.cn/api/v1/web_hooks/fire

Successfully deployed webhook for all gems to http://example.com

活动方法

GET - `/api/v1/activity/latest`

获取最近添加到 RubyGems.org 的 50 个 gem（首次添加）。返回 gem 的 JSON 或 YAML 表示形式的数组。

$ curl 'https://rubygems.org.cn/api/v1/activity/latest.json'

GET - `/api/v1/activity/just_updated`

获取最近更新的 50 个 gem。返回 gem 版本的 JSON 或 YAML 表示形式的数组。

$ curl 'https://rubygems.org.cn/api/v1/activity/just_updated.json'

其他方法

GET - `/api/v1/api_key.(json|yaml)`

使用 HTTP 基本身份验证检索您的 API 密钥。

$ curl -u "[email protected]:schwwwwing" \
       https://rubygems.org.cn/api/v1/api_key.json

{
  "rubygems_api_key": "701243f217cdf23b1370c7b66b65ca97"
}

GET - `/api/v1/dependencies?gems=[用逗号分隔的 GEM 名称]`

返回给定 gem 的所有版本的哈希的序列化数组。每个哈希包含一个 gem 版本及其依赖项，这对于解决依赖项很有用。

$ ruby -ropen-uri -rpp -e \
  'pp Marshal.load(open("https://rubygems.org.cn/api/v1/dependencies?gems=rails,thor"))'

[{:platform=>"ruby",
  :dependencies=>
   [["bundler", "~> 1.0"],
    ["railties", "= 3.0.3"],
    ["actionmailer", "= 3.0.3"],
    ["activeresource", "= 3.0.3"],
    ["activerecord", "= 3.0.3"],
    ["actionpack", "= 3.0.3"],
    ["activesupport", "= 3.0.3"]],
  :name=>"rails",
  :number=>"3.0.3"},
...
{:number=>"0.9.9", :platform=>"ruby", :dependencies=>[], :name=>"thor"}]

API 授权

Ruby 库

速率限制

Gem 方法

GET - /api/v1/gems/[GEM NAME].(json|yaml)

GET - /api/v1/search.(json|yaml)?query=[YOUR QUERY]

GET - /api/v1/gems.(json|yaml)

POST - /api/v1/gems

DELETE - /api/v1/gems/yank

GET - /api/v1/gems/[GEM NAME]/reverse_dependencies.json

Gem 版本方法

GET - /api/v1/versions/[GEM NAME].(json|yaml)

GET - /api/v1/versions/[GEM NAME]/latest.json

GET - /api/v1/timeframe_versions.json

Gem 下载方法

GET - /api/v1/downloads.(json|yaml)

GET - /api/v1/downloads/[GEM NAME]-[GEM VERSION].(json|yaml)

所有者方法

GET - /api/v1/owners/[USER HANDLE|USER ID]/gems.(json|yaml)

GET - /api/v1/gems/[GEM NAME]/owners.(json|yaml)

POST - /api/v1/gems/[GEM NAME]/owners

DELETE - /api/v1/gems/[GEM NAME]/owners