REST API とは？リソース指向の Web API

REST API は、URL でリソースを公開し、標準的な HTTP メソッドでそれらを操作し、JSON のような構造化データを返す Web インターフェースです。

REST（Representational State Transfer の略）は、Web API の主流のスタイルです。ユーザー、build、deployment などのリソースはそれぞれ URL を持ち、GET、POST、PUT、DELETE でそれらを操作します。ほとんどの CI ツールは、プラットフォームの REST API を呼び出して自動化を行うため、REST を理解するとパイプラインの連携を読み解いてデバッグするのに役立ちます。

リソースと URL

REST では、すべてのエンティティが /deployments/42 のような URL で識別されるリソースです。名前付き関数を呼び出すのではなく HTTP メソッドで操作するため、インターフェースが予測しやすく保たれます。

メソッドはアクションに対応する

GET はリソースを読み取ります。
POST は新しいものを作成します。
PUT または PATCH は既存のものを更新します。
DELETE はそれを削除します。

status code が意味を持つ

REST は結果の報告を HTTP status code に頼ります。成功は 200、作成は 201、不正なリクエストは 400、認証の問題は 401 や 403、見つからない場合は 404、サーバーエラーは 5xx です。パイプラインはこれらを読んで、続行するか失敗させるかを判断します。

認証

REST API は通常、Authorization ヘッダーで送信される、多くの場合 bearer トークンや OAuth 認証情報などのトークンを必要とします。CI はそのトークンを秘密情報として保存し、各呼び出しに付加します。

CI/CD における REST API

デプロイのトリガー、release の作成、status check の投稿、build 結果の照会は、多くのパイプラインですべて REST 呼び出しです。2xx 以外のレスポンスは、その step が失敗またはリトライすべきというシグナルです。

flaky な API 呼び出しへの対処

idempotent な GET での 5xx や接続の切断は通常リトライして安全ですが、4xx はリクエストが間違っていることを意味し、リトライしても解決しません。Latchkey の runner は、一般的な API エンドポイントへの一時的なネットワーク障害を自動的にリトライするため、上流の短時間のしゃっくりがデプロイの step を壊すことはありません。

重要なポイント

REST は URL でリソースを公開し、標準的な HTTP メソッドでそれらを操作します。
status code が結果を報告するため、2xx 以外のレスポンスがパイプラインの判断を左右します。
5xx やネットワークエラーでは idempotent な呼び出しをリトライしますが、4xx では決してリトライしません。