APIと連携

このカテゴリの対象

ここには関連する4つの仕事があります。リクエストを手作業で組み立ててテストすること。他の人が使えるようにインターフェースを文書化すること。複数のサービスの前にゲートウェイを置き、キー、レート制限、クォータ、バージョンの挙動をどこでも揃えること。そもそも連携を想定していない製品の間でデータを動かすこと。

最初の3つは、APIを提供するチームのためのものです。4つ目は、購入したツールをつなぎ合わせる人のためのものです。両方の層がこの棚に来るため、製品どうしがまるで違って見えます。

コードを使わない純粋なビジュアル自動化は、ノーコードと自動化に入ります。稼働中のサービスへのアラートは、監視です。

クライアントと、いま何が差を生むか

どのクライアントも、リクエストを送ってレスポンスを表示します。違いはその先にあります。

最初は環境の扱いです。ローカル、ステージング、本番、そして同僚がノートPCで動かしているものを、誰もURLを手で書き換えずにきれいに切り替えられること。次にスクリプトで、毎朝トークンを貼り付けるのではなく、リクエストの前に取得できること。そしてテストのアサーションで、コレクションをビルドサーバーが実行できるものにすることです。

意見が分かれるのは共同作業です。クラウド同期は便利ですが、リクエストの履歴が他社のサーバーに置かれます。ファイルベースのツールは、コレクションをコードの隣のリポジトリで管理するので、変更は他と同じようにレビューされ、退職する社員がワークスペースごと持ち出すこともありません。

どちらの場合でも、シークレットがどこにあるかを尋ねてください。書き出したコレクションに書き込まれたキーは、公開リポジトリへの定番の経路です。

腐らないドキュメント

手書きのドキュメントは、四半期のうちに古くなります。生き残る方法は、コードと一緒に管理され、コードのマージで再構築される仕様から生成することだけです。

3点を確認してください。変換の手順なしに、自社の仕様形式を読めるか。ページ上から例を実行できるか。まだ使っている人のために、古いバージョンが公開されたままになるか。

変更履歴は、デザインよりも重要です。利用者は何がいつ壊れたかを知る必要があり、どんなスタイリングもその代わりにはなりません。

ゲートウェイと、それが必要になるとき

サービスが1つだけなら、ゲートウェイはまず必要ありません。必要になるのは、認証、レート制限、クォータ、バージョン管理を、複数のサービスで同じように動かさなければならなくなったときです。

その時点での確認事項は次のとおりです。どこで動き、どれだけの遅延が加わるか。制限はどう定義され、上限に達したとき呼び出し側には何が見えるか。キーをダウンタイムなしにローテーションできるか。ログには何が含まれるか。トラフィックを終端するものはすべて、それ自体が可用性のリスクになるので、ゲートウェイ自体の調子が悪い日に何が起きるかを尋ねてください。

料金の計測単位

• クライアントとドキュメント製品では席数。閲覧専用のレビュー担当は無料の場合もあります。
• 連携プラットフォームではタスクまたは実行回数。ワークフローごとではなく、ステップごとに数えます。
• ゲートウェイでは呼び出し数または帯域。キャッシュされたものは別の料率です。
• 実行履歴の保持期間。エントリープランでは短く、必要なときにちょうど足りません。
• コネクタ。上位のものは、提示されたプランの一つ上の階層に置かれています。

タスク課金は、署名する前に計算してください。6ステップのワークフローを10分おきに動かすと、月に1タスクではありません。その数字に驚いたチームは少なくありません。他のカテゴリでも見られる同じ種類の驚きは、料金ページが隠していることにまとめています。

試すこと

すでに動かしている実際の連携を1つ、相手側がエラーを返す部分も含めて、最初から最後まで作り直してください。

リトライ、重複配信、止まったサードパーティ、フィールドが欠けたペイロードを、ツールがどう扱うかを見ます。よくできた製品は、原因を直したあとに失敗した実行を再生できます。弱い製品は黙って失い、お客様が気づくまで何も知らせません。

そのうえで、出口を確認します。コレクション、仕様、ワークフロー定義は、読めるファイルとして書き出せるべきです。ワークスペースの中に閉じ込められたものは、2度作ることになる作業です。

ドキュメント、バージョン管理、利用者をつなぎとめること

利用者のいるインターフェースは約束であり、このカテゴリの難しさの大半は、その約束を破らずに変更することから来ます。

最初の外部の利用者が現れる前に、バージョン管理の方針を決めてください。あとから追加しようとすると、全員に一斉の変更をお願いすることになります。方式が何であれ、何がいつ変わったかを公開し、非推奨の期間は数週間ではなく数か月で見積もります。

エラーにも、成功と同じだけの注意を払ってください。何が起きたか、どのフィールドが原因か、次に何をすべきかを伝えるレスポンスは、どれだけの文章よりも多くのサポート依頼を減らします。

そして、自社のドキュメントを新参者の目で読んでください。最も手早い改善は、たいてい参照表ではなく、ページの先頭にある動く例です。