$30 off During Our Annual Pro Sale. View Details »

APIをもっと使ってもらうには?- APIファースト戦略のすすめ / Recommendati...

APIをもっと使ってもらうには?- APIファースト戦略のすすめ / Recommendation of API-first strategy

Presentation Slides for Postman Tokyo Meetup 2023.11
Session title: APIをもっと使ってもらうには? - APIファースト戦略のすすめ
Date: 2023/11/08

Yoichi Kawasaki

November 08, 2023
Tweet

More Decks by Yoichi Kawasaki

Other Decks in Technology

Transcript

  1. APIにまつわるさまざまな課題 • 利用者ニーズ、シナリオにマッチしない • 再利用性 / 汎用性がない • 十分な認証・認可、セキュリティ対策がされていない •

    一貫性がない • 適切なエラーハンドリングがされていない • パフォーマンスや拡張性がない • バージョン管理が不十分、互換性が維持されない • 標準化仕様がサポートされていない • APIドキュメントがない、見つからない • APIドキュメントが古い • APIが見つからない
  2. 2023 State of the API Report https://www.postman.com/state-of-api/executing-on-apis/#obstacles-to-consuming-apis #1 ドキュメント不足 (52%)

    #2 APIの発見が困難 (32%) #3 時間がない(28%) #4 知識不足(26%) #5 予算不足(23%) #6 人員不足(22%) #7 APIの再利用が困難 (19%) API利用における障壁
  3. APIファースト戦略とは? • APIに対する位置づけ、考え方 ◦ APIはプロダクト(主要ソフトウェア構成要素、主要ビジネスアセット) ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心:内外サービスをAPIを通じて活用しビルディングブロックで構築 •

    API開発モデル ◦ APIを最優先に開発(APIを後回しにしない) ◦ コードを書く前にAPIを設計・構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/
  4. コードを書く前にAPIを設計・構築するとは? 要件 API設計 コード API Spec作成 APIドキュメント作成 モック作成 テストコード作成 API定義・生成

    テスト モック、テスト結果を元にレビューや フィードバックを受け設計内容を洗練させ る作業を繰り返す
  5. API設計の指針 • ユーザーファースト ◦ API設計をユーザーの視点から行う • RESTful原則の遵守 ◦ リソース、エンドポイント、HTTPメソッドなど •

    エラーハンドリング ◦ エラーハンドリングの仕組み、一貫性のあるエラーコードやメッ セージ、適切なステータスコード • バージョニング ◦ しっかりバージョン管理、互換性を維持 • セキュリティ ◦ 適切な認証・認可メカニズムの導入やデータの暗号化、など • 性能と拡張性 ◦ リクエストとレスポンス最適化、キャッシング戦略、など • 明確なAPI仕様と詳細ドキュメント • Microsoft learn: RESTful Web API の設計 • 政府CIOポータル: APIテクニカルガイドブック
  6. 2つのAPI開発モデルを比較 要件 要件 コード API設計 API Docs / Tests コード

    Comment Annotation API Spec API Docs API Mock API Tests コードファースト APIファースト
  7. コードファースト開発モデル 要件 コード API Docs / Tests ポイント • 要件を元にAPI実装後にAPIテスト・ドキュメント作成。

    • 焦点はAPI (インターフェース) ではなくコア機能。APIは後付 け。APIを実装する段階になるとコア機能はほぼ完了 メリット - 迅速なプロトタイピング - 柔軟性と適応力。要件の変更や市場の変化に迅速に対応 デメリット - API内容がコア機能や利用テクノロジーに引っ張られやすい - APIドキュメントや結合テストが後付けになるため、品質リスクや途中開発 における関係者間のコラボレーションへの弊害 - 仕様確定やテスト実施によるフィードバックが開発プロセス後半になるた め、問題がある場合の変更コストが大きい
  8. APIファースト開発モデル ポイント • APIコードを書く前にAPIを設計・構築 • API設計フェーズでフィードバックループを通じて設計内容を洗 練化 メリット • 設計品質、開発者エクスペリエンス向上

    • 要件・設計などの問題について早期発見ができ、変更コストが低いうちに変 更、方向転換ができる。不確実性に対して柔軟。 • 設計段階で、APIドキュメントやテスト生成され、比較的初期段階でも関係 者間でコラボレーションが可能 デメリット • 設計フェーズに時間がかかる • 要件の変更に対する対応に時間がかかりがち(設計から入るため) 要件 コード API設計
  9. APIファースト戦略 Recap • APIに対する位置づけ、考え方 ◦ APIはプロダクト(主要ソフトウェア構成要素、主要ビジネスアセット) ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心:内外サービスをAPIを通じて活用しビルディングブロックで構築

    • API開発モデル ◦ APIを最優先に開発(APIを後回しにしない) ◦ コードを書く前にAPIを設計・構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/ 再掲
  10. API設計支援ツール - APIビルダー OpenAPI Postman Collection RAML WSDL GraphQL ProtoBuf

    チームによるAPI設計を支援するツールです。直感的なUIを介してAPIの構造を定義できます APIビルダーの主要機能 • API設計 ◦ スキーマ定義(インポートも可能) ◦ API定義のバリデーション ◦ 定義からサーバーコード生成 ◦ テスト、ドキュメント生成 ◦ コレクション生成 • チーム開発支援 ◦ チーム間のAPI共有 ◦ コメント、Changelog • APIバージョン管理 ◦ コードリポジトリ(GitHub, GitLab, Bitbucket, and Azure)と同期 API設計
  11. Postmanスクリプトでテストや自動化を記述 • Postman サンドボックスで実行 • Built-inのJavaScript APIをpm、postmanオブジェクトを通じて利用可能 • Mochaベースのテストフレームワークを利用、AssertionライブラリとしてChaiが利用可能 •

    豊富なスニペットとサンプルスクリプト集が用意されている • 新機能: Postbot(AIを活用したスクリプト生成アシスタント) スクリプト Postbot スニペット ローコード 支援機能 テスト
  12. モニターで複数エリアから定期的にAPIテスト実行 • コレクションごとにモニターを設定 • テスト実行頻度 ◦ 5分毎〜設定可能。ただし無料プランは一時間毎〜 • テスト実行リージョン選択 ◦

    複数リージョンからの APIテスト実行が可能 • スタティックIPを持つモニター指定 ◦ 要Professional / Enterpriseプラン • アラート通知設定 ◦ メール通知、or インテグレーション設定 でslack、 PagerDutyなど他チャンネルへの通知も可能 • リトライ、タイムアウトなど設定可能 リクエスト元リージョンの選択 https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/ 監視・観測
  13. APIセキュリティとガバナンスの管理 代表的なチェック・管理内容。各フェーズやCI/CDなどからの継続的な実施が可能 APIセキュリティ • セキュリティ衛生状態 • 認証と認可の脆弱性 • 読み取りと書き込みの粒度 •

    クォータとスロットリングの実装 • 適切なセキュリティヘッダー • ロギングとモニタリングの実践 • API文書の適切な管理 • カスタムルール、etc. https://www.postman.com/api-platform/api-security/ APIガバナンス • APIの文書化、テスト実施、メンテナンス状況、 誤ってトークンを公開していないか、など APIご と、組織ごとに、個別もしくは全体統制の設定 • カスタムルール、etc. https://www.postman.com/api-platform/api-governance/ テスト (非機能要件)
  14. Postman APIネットワーク - APIの発見・探索・共有 Postman API ネットワークは、 API 利用者と API

    提供者の双方が API を簡単に発見、探索、共有でき るユニークな場所を提供します。 Postman API ネットワークには2つの種類があります: パブリック APIネットワーク プライベート APIネットワーク APIネットワーク ディスカバリ
  15. パブリックAPIネットワーク パブリックAPIネットワークは、あらゆる利用者に公開されているAPIが含まれる世界最大規模のパブリッ クAPI成果物のカタログです。パブリックワークスペースを通じて組織のパブリック API を簡単に共有し たり、Salesforce、Paypal、Notion のような企業の何千ものパブリック API を発見したりすることがで きます。

    • 広範な利用者・開発者へのアクセス • 利用者のTime to first callの短縮化 ◦ 利用者は公開されているコレクションを Forkして利用 ◦ 利用者のAPIテストが容易になる • 利用者からのフィードバックと改善 ディスカバリ 2023年9月〜 日本語検索サポート