API開発健全性 〜 持続可能で高品質なAPIのためのアプローチ 〜

本セッションではPostmanを活用したAPIの設計、開発、運用プロセス全体における持続可能で高品質な状態を保つためのアプローチをご紹介します。継続的テストとモニタリング、高品質なドキュメンテーションや効率的なチーム開発などを通じた長期的に信頼できるAPIを構築・維持を目指します。開発健全性ミートアップ ~ GitHub × Postman × Atlassian ~での発表資料です。

Transcript

1. All rights reserved by Postman Inc API 開発健全性 〜 持続可能で高品質な API のためのアプローチ 〜 草薙 昭彦 テクノロジーエバンジェリスト #開発健全性
2. テクノロジーエバンジェリスト Postman 株式会社 草薙 昭彦 @postman_japan @nagix
3. @postman_japan
4. コンピューターの歴史 @postman_japan 1 2 3 4 「API ファーストの世界」より https://www.api-first-world.com/ja/
5. API 利用が急増している背景 @postman_japan モバイル デスクトップ 利用者 インフラストラクチャ モノリス マイクロサービス アーキテクチャ オンプレミス クラウド
6. 2024 State of the API レポート @postman_japan https://www.postman.com/state-of-api/2024/
7. 健全な API 開発って？ @postman_japan 生産性が高い 効率が良い 見通しが良い ストレスが 少ない 開発組織や サービスの 魅力が向上
8. 健全な API 開発って？ • API を利用し始めるステップがスムーズ • チームで開発するときに変更が周知されている • 継続的に API がテストされ、問題が早い段階で明らかになっている • 運用開始後も API の品質が保たれている @postman_japan
9. オンボーディングの課題 @postman_japan 社内のベテランに聞かないと使い方がわからない ドキュメントどこいった 実装とドキュメントの内容が合っていない 認証ステップが複雑すぎる API 利用者はコード実装する開発者だけではないよ
10. オンボーディングの課題 @postman_japan 開発者が API 作業の大半を占めているが、これはモダンな API 開発が異なる組織レベルにまたがる共同作 業の性質を反映している。
11. チームコラボレーションの課題 @postman_japan 管理すべき API の数は増える一方 情報の整理が個人頼みで、共有が十分に行われていない API の粒度や品質がバラバ ラで統一感や整合性がない 重複した機能が別々のチームで行わ れていて車輪の再開発が起きている
12. チームコラボレーションの課題 @postman_japan 開発者の 58%は API を学ぶために社内ドキュメントに頼っているが、39%は一貫性のない文書が最大の障 害になっていると答えている。 社内ドキュメント 58% ソースコードレポジトリ 44% 同僚に聞く 43%
13. 開発中の問題解決における課題 @postman_japan 本番稼働直前にアーキテクチャに関わる問題が発覚しても直せない API の修正が入るなら早いうちにしてもらわないとフロント側の改修が テストスクリプトが散在していて、 ちゃんと管理がされていない 継続的にテストを回していないと、問 題箇所の特定に時間がかかる
14. 開発中の問題解決における課題 @postman_japan 1％が API をテストしていないことを認めており、驚くべきことにセキュリティテストを重視しているのはわずか 37％。統合テストと機能テストがよく実施されている一方、API は脆弱なままである。
15. 運用開始後の課題 @postman_japan 気づかないうちに API のレスポンス時間が上がっていた 特定の時間だけエラーの報告がある 特定の地域だけ不具合の報告がある
16. 運用開始後の課題 @postman_japan API の変更は、追加、編集、廃止のいずれにせよ日常的に発生する。しかし、変更を管理する適切なツールがな ければ、不整合、変更による動作不良、潜在的なセキュリティリスクにつながる課題に直面する。
17. Postman がおすすめ するアプローチとは @postman_japan
18. Postman コレクション = 実行可能 API ドキュメント • コレクション は API リクエストをグループにして整理した、基本となるデータ構造 • コレクションを一言でいうと、実行可能な API ドキュメント コレクション APIリクエスト テスト サンプル APIリクエスト テスト サンプル APIリクエスト テスト サンプル @postman_japan
19. API 認証ステップの軽減 @postman_japan ここで入力した情報は自動的にリクエストヘッダーにセットされる Bearer トークン アクセストークンを入力 Bearer トークンを選択 認証タブを選択
20. API 認証ステップの軽減 @postman_japan OAuth 2.0 OAuth 2.0 を選択 トークンの設定を設定後、トークンを取得すると取得 したトークンが自動的に入力される
21. ワークスペースを使ったコラボレーション @postman_japan ユーザー A ユーザー B チームワークスペース 他のメンバーもアクセス できる場所で直接読み書き Free プランでは 3人までのチーム 4人以上のチーム は有料プラン
22. API の発見を助ける API ネットワーク @postman_japan プライベート API ネットワーク パブリック API ネットワーク • チームメンバーに限定 • チーム内の機能重複の排除 • API 知見やノウハウの共有 • チーム内の API 利用動向の把握 • 多くの利用者・開発者に知ってもらう • 利用者の Time To First Call の短縮 • 利用者からのフィードバックと改善
23. パブリック API ネットワーク API の発見を助ける API ネットワーク @postman_japan プライベート API ネットワーク コレクション パブリックワークスペース コレクション コレクション コレクション パブリックワークスペース コレクション コレクション 世界中の Postman ユーザーがアクセス チームメンバー（社内ユーザー）がアクセス チームワークスペース コレクション コレクション チーム A チーム B
24. コレクションと API テストスクリプトの関係 テストとは、コレクションに追加する API リクエスト (群) に対するテスト コレクション API リクエスト① テスト サンプル API リクエスト② テスト サンプル API リクエスト③ テスト サンプル テストスクリプト 各リクエストのテスト結果 複数リクエストで構成されたシナリオテストも作れる Request ① POST /regist Request ② GET /get Request ③ POST /unregist @postman_japan
25. 実行 実行結果詳細表示 サマリー結果表示 順番入れ替え可能 実行方法選択 手動 / スケジュール実行 イテレーション数 遅延秒数 データファイル 指定可能 選択 コレクションメニュー コレクションランナー実行方法設定 @postman_japan コレクションランナーによる自動化 複数リクエストのテストをまとめて実行
26. コレクションもしくはフォルダーに登録されている API リクエスト群（シナリオ）に対して、手軽に API クライアント から負荷をかけ、API の性能フィードバックをリアルタイムで取得可能 実行 コレクションランナー実行タイプ設定 Postman パフォーマンステスト 複数のリクエストで構成されるシナリオに対してパフォーマンステスト実行
27. モニターで定期的に API の健全性をテスト • コレクションごとにモニターを設定 • テスト実行頻度 ◦ 5 分毎〜設定可能。ただし無料プランは 1 時間毎〜 • テスト実行リージョン選択 ◦ 複数リージョンからの API テスト実行が可能 • スタティック IP を持つモニター指定 ◦ 要 Professional / Enterpriseプラン • アラート通知設定 ◦ メール通知、or インテグレーション設定 で Slack、 PagerDuty など他チャンネルへの通知も可能 • リトライ、タイムアウトなど設定可能 リクエスト元リージョンの選択 Setup a monitor in Postman https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/ @postman_japan
28. オブザーバービリティサービスとの連携 インテグレーション設定により Postman モニターで閾値を越えた失敗数が確認されたら、 外部オブザーバービリティサービスにイベント送信が可能 イベント 送信 PagerDuty Datadog New Relic Observe your API performance using monitor integrations https://learning.postman.com/docs/designing-and-developing-your-api/observing-an-api/observing-an-api/ @postman_japan Datadog dashboardイメージ
29. まとめ • 開発効率の改善と並んで、開発における健全性の維持・向上は、組織や最終プロ ダクトの魅力を引き上げる • Postman は開発者体験を向上させる多くの機能を提供 ◦ オンボーディングの課題には Postman コレクション 、認可ガイド ◦ チームコラボレーションの課題にはワークスペース ◦ 開発中の早期の問題解決のために コレクションランナー 、パフォーマンステスト ◦ 運用開始後の問題検出のために API モニタリング @postman_japan
30. ダウンロードして無料でスタート！ https://www.postman.com/downloads/ デスクトップアプリ • Windows • Mac • Linux Web アプリ • アカウント登録で同 じ機能をブラウザで も利用できる @postman_japan
31. Postman Japan コミュニティ Discord Discord サーバーを開設しました！ 今後 Postman のプロダクトアップデートやイベン ト情報の配信や、みなさんとの交流の場として活 用していきたいと思います。 https://discord.gg/G4SQWDDqVa @postman_japan
32. Postman Connpass グループ API Night（勉強会）& ワークショップ https://postman.connpass.com/ Postman イベントにぜひご参加ください Postman Japan X アカウント @postman_japan @postman_japan
33. ありがとうございました @postman_japan