Go

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

使うもの

Go向けの公式モジュールはありません。 go getするものはなく、net/http・encoding/json・net/url、署名検証にcrypto/hmacとcrypto/sha256——すべて標準ライブラリです。

このドキュメントでは、レスポンスをその場でHTTPクライアントに渡す薄いClient型と、フィールドをタグで書いた構造体で受け取る形にしています。map[string]anyで受けることもできますが、フィールドIDの打ち間違いがコンパイル時に見つからなくなるので勧めません。

向いている用途

• Goで書いたWebサーバーに、お知らせ・導入事例・ドキュメントなど「エンジニアが触らない原稿」の置き場を足す
• Hugoの外で、ビルド時に記事を取り出して静的HTMLへ流す小さなジェネレーターを書く
• 記事の変更をWebhookで受け、キャッシュの破棄や再ビルドを起動する常駐プロセスを置く
• 定期実行で記事一覧を取り出し、別のシステムへ同期する

向いていない用途

• 記事の書き込み・更新。 配信APIは読み取り専用です。原稿の作成と公開は管理画面から行います。
• スキーマからの型生成。 @genko-me/cliが生成するのはTypeScriptの型定義です。Go側の構造体は管理画面のスキーマに合わせて自分で書きます。
• 下書き一覧の表示。 draftKeyで取得できるのは単一コンテンツだけです。
• 全文検索の基盤。 qは大文字小文字を区別しない部分一致で、関連度順にも形態素解析にも対応していません。

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

ハンドラの中から毎回配信APIを呼ぶと、ページ表示のたびに外部へのHTTPが1往復増えます。配信APIの上限はAPIキーごとに1分300リクエストです。取得結果をプロセス内のキャッシュに保持し、Webhookで破棄する組み方にしてください。

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

http.Clientは使い回してください。呼び出しのたびに新しく作ると、コネクションが再利用されません。Timeoutは必ず設定します。既定のhttp.DefaultClientにはタイムアウトがなく、応答が返らないと待ち続けます。

次に読む

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