RubyGems 導覽選單
指南

透過 HTTP 與 RubyGems.org 互動的詳細資訊。

注意：API 仍在開發中，歡迎您提供協助！ RubyGems 本身和 RubyGems 寶石 使用 API 來發布寶石、新增擁有者等等。

API 授權

某些 API 呼叫需要授權標頭。若要建立或檢視現有的 API 金鑰，請在登入 RubyGems.org 後，按一下您的使用者名稱、「設定」，然後按一下「API 金鑰」。以下是使用 API 金鑰的範例

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

如果您使用多重身分驗證，您需要在 OTP 標頭中提供一次性密碼。以下是使用您的 API 金鑰與 OTP 的範例

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

Ruby 函式庫

您也可以使用 Ruby 與 RubyGems.org 互動。

gems 函式庫提供 Ruby 介面，可使用以下列出的所有資源。此函式庫具有 完整文件，其中包括自述檔案中的一些基本使用範例。您可以使用指令安裝函式庫

gem install gems

速率限制

請參閱 RubyGems.org 速率限制

Gem 方法

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

傳回關於指定 gem 的一些基本資訊。請參閱下方以 JSON 格式呈現的 gem「rails」範例回應

$ curl https://rubygems.org/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": "http://rubygems.org/gems/rails",
  "gem_uri": "http://rubygems.org/gems/rails-3.2.1.gem",
  "homepage_uri": "http://www.rubyonrails.org",
  "wiki_uri": "http://wiki.rubyonrails.org",
  "documentation_uri": "https://rails-api.dev.org.tw",
  "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 上提交搜尋，以搜尋 active gem，就像網站上的搜尋查詢一樣。傳回與之相符的 gem 的 JSON 或 YAML 陣列表示形式。

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

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

結果分頁，因此 API 呼叫只會傳回前 30 個相符的 gem。若要取得後續結果，請使用頁面查詢參數，直到收到空白回應為止。

$ curl 'https://rubygems.org/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/api/v1/gems.json

POST - /api/v1/gems

將 gem 提交至 RubyGems.org。必須在要求主體中張貼已建立的 RubyGem。

$ curl --data-binary @gemcutter-0.2.1.gem \
       -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       https://rubygems.org/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/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/api/v1/gems/shoulda/reverse_dependencies.json

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

Gem 版本方法

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

傳回類似以下的寶石版本詳細資料陣列

$ curl https://rubygems.org/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/[寶石名稱]/latest.json

傳回包含特定寶石最新版本的物件。

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

{
  "version": "4.2.1"
}

GET - /api/v1/timeframe_versions.json

傳回在時間戳記參數指定的時段內建立的寶石版本陣列。

需要一個名為 from 的 iso8601 時間戳記參數。這是您要開始查詢的時間。您可以包含一個名為 to 的 iso8601 時間戳記參數。如果存在，則只會傳回在 from 和 to 之間建立的版本。如果未提供 to，則會傳回在 from 和目前時間之間建立的所有版本。

注意：您使用 from 和 to 指定的時段不能超過 7 天。

結果會分頁，因此 API 呼叫只會傳回您時段中的前 30 個版本。若要取得後續結果，請使用頁面查詢參數，直到收到空白回應。

範例回應

$ curl 'https://rubygems.org/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": "https://127.0.0.1/gems/rails",
  "gem_uri": "https://127.0.0.1/gems/rails-6.0.0.beta1.gem",
  "homepage_uri": "http://rubyonrails.org",
  "wiki_uri": "",
  "documentation_uri": "https://rails-api.dev.org.tw",
  "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": []
}]

寶石下載方法

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

傳回包含 RubyGems 上下載總數的物件。

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

{
  "total": 461672727
}

GET - /api/v1/downloads/[寶石名稱]-[寶石版本].(json|yaml)

傳回包含特定寶石下載總數以及指定版本下載總數的物件。

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

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

擁有者方法

GET - /api/v1/owners/[使用者代號|使用者 ID]/gems.(json|yaml)

查看使用者的所有寶石。這是使用者可以推送到所有寶石。可以使用使用者代號或使用者 ID 要求擁有者寶石清單。

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

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

GET - /api/v1/gems/[寶石名稱]/owners.(json|yaml)

查看寶石的所有擁有者。這些使用者都可以推送到此寶石。

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

[
  {
    "email": "nick@gemcutter.org"
  },
  {
    "email": "ddollar@gmail.com"
  }
]

POST - /api/v1/gems/[寶石名稱]/owners

將擁有者新增到您擁有的 RubyGem，授予該使用者管理權限。

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'email=josh@technicalpickles.com' \
       https://rubygems.org/api/v1/gems/gemcutter/owners

Owner added successfully.

DELETE - /api/v1/gems/[寶石名稱]/owners

移除使用者管理您擁有的 RubyGem 的權限。

$ curl -X DELETE -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
        -d "email=josh@technicalpickles.com" \
        https://rubygems.org/api/v1/gems/gemcutter/owners

Owner removed successfully.

個人資料方法

GET - /api/v1/profiles/[使用者代號|使用者 ID].(json|yaml)

查看使用者的基本使用者資訊。

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

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

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

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

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

檢視您帳戶的基本使用者資訊，包括多重驗證狀態。需要傳遞使用者名稱和密碼。

$ curl -u "nick@gemcutter.org:schwwwwing" \
       https://rubygems.org/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/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 參數，指定 * 可將勾子套用至所有寶石。

$ curl -X POST -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'gem_name=rails' -F 'url=http://example.com' \
       https://rubygems.org/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/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 參數，指定 * 可將勾子套用至所有寶石。

$ curl -X DELETE -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -d 'gem_name=rails' -d 'url=http://example.com' \
       https://rubygems.org/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/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 參數，指定 * 可將勾子套用至所有寶石。

每個觸發的 Webhook 都包含一個 Authorization 標頭，讓您可以確定要求來自 RubyGems.org。標頭的值是寶石名稱、寶石版本和您的 API 金鑰的 SHA2 雜湊串接。

$ curl -H 'Authorization:rubygems_b9ce70c306b3a2e248679fbbbd66722d408d3c8c4f00566c' \
       -F 'gem_name=rails' -F 'url=http://example.com' \
       https://rubygems.org/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/api/v1/web_hooks/fire

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

活動方法

GET - /api/v1/activity/latest

提取最近新增至 RubyGems.org 的 50 個寶石（首次）。傳回寶石的 JSON 或 YAML 表示形式陣列。

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

GET - /api/v1/activity/just_updated

提取最近更新的 50 個寶石。傳回寶石版本的 JSON 或 YAML 表示形式陣列。

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

其他方法

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

使用 HTTP 基本驗證來擷取您的 API 金鑰。

$ curl -u "nick@gemcutter.org:schwwwwing" \
       https://rubygems.org/api/v1/api_key.json

{
  "rubygems_api_key": "701243f217cdf23b1370c7b66b65ca97"
}

GET - /api/v1/dependencies?gems=[以逗號分隔的寶石名稱]

傳回給定寶石所有版本的雜湊陣列。每個雜湊包含一個寶石版本及其相依性，這對於解析相依性很有用。

$ ruby -ropen-uri -rpp -e \
  'pp Marshal.load(open("https://rubygems.org/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"}]
上一個 下一個