Ruby

genko.meの配信APIは、X-API-KEYヘッダーを付けてGETし、JSONを受け取るだけのREST APIです。Rubyからは標準添付のnet/httpとjsonだけで扱えます。

使うもの

Ruby向けの公式gemはありません。 Gemfileに足すものはなく、net/http・json・uri、署名検証にopenssl——すべて標準添付ライブラリです。

Faradayやhttprbを既に使っているプロジェクトなら、そちらに載せ替えても構いません。配信APIはヘッダーが1つとクエリだけなので、HTTPクライアントを選びません。このドキュメントでは依存を増やさないnet/httpで書きます。

向いている用途

• Railsアプリに、お知らせ・導入事例・採用情報など「エンジニアが触らない原稿」の置き場を足す
• Jekyll・Bridgetown・middlemanなどRubyの静的サイトジェネレーターのビルドで記事を取り出す
• Sinatraの小さなサイトで、更新の多いページだけCMS管理に移す
• rakeタスクや定期処理で、記事の一覧を取り出して別のシステムへ流す

向いていない用途

• 記事の書き込み・更新。 配信APIは読み取り専用です。原稿の作成と公開は管理画面から行います。
• ActiveRecordのように扱うこと。 配信APIはHTTPのGETだけで、関連の遅延読み込みも、whereのチェーンもありません。参照の展開はdepthで段数を指定します。
• 下書き一覧の表示。 draftKeyで取得できるのは単一コンテンツだけです。
• 全文検索の基盤。 qは大文字小文字を区別しない部分一致で、関連度順にも形態素解析にも対応していません。

リクエストのたびに取りに行かない

Railsのコントローラから毎回net/httpを呼ぶと、ページ表示のたびに外部へのHTTPが1往復増えます。配信APIの上限はAPIキーごとに1分300リクエストです。Rails.cache.fetchなどで取得結果をキャッシュし、Webhookで破棄する組み方にしてください。

配信APIのレスポンスにはCache-Control: private, no-storeが付きます。中間のHTTPキャッシュは効かないので、キャッシュはアプリ側で持ちます。

次に読む

• 導入：APIキーの設定から、一覧と詳細の表示まで
• 実践：ページ送り、下書きプレビュー、Webhookの署名検証
• 配信API：エンドポイントとレスポンスの仕様