Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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. All rights reserved by Postman Inc
    APIをもっと使ってもらうには?
    APIファースト戦略のすすめ
    川崎庸市
    Postman株式会社
    Presentation slides for Postman Tokyo Meetup 2023.11

    View full-size slide

  2. Technology Evangelist
    Postman株式会社
    川崎 庸市 / Yoichi Kawasaki
    @yokawasa
    @postman_japan

    View full-size slide

  3. APIをもっと使ってもらうには?

    View full-size slide

  4. APIにまつわるさまざまな課題
    ● 利用者ニーズ、シナリオにマッチしない
    ● 再利用性 / 汎用性がない
    ● 十分な認証・認可、セキュリティ対策がされていない
    ● 一貫性がない
    ● 適切なエラーハンドリングがされていない
    ● パフォーマンスや拡張性がない
    ● バージョン管理が不十分、互換性が維持されない
    ● 標準化仕様がサポートされていない
    ● APIドキュメントがない、見つからない
    ● APIドキュメントが古い
    ● APIが見つからない

    View full-size slide

  5. 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利用における障壁

    View full-size slide

  6. レポート結果から分かる
    APIをもっと使ってもらうためにすべきこと
    良質なAPIドキュメントを用意する
    APIを見つけやすくする
    再利用性 / 汎用性のあるAPIを用意する

    View full-size slide

  7. レポート結果から分かる
    APIをもっと使ってもらうためにすべきこと
    良質なAPIドキュメントを用意する
    APIを見つけやすくする
    再利用性 / 汎用性のあるAPIを用意する
    API設計
    API設計 API構築
    API
    ディスカバリ

    View full-size slide

  8. レポート結果から分かる
    APIをもっと使ってもらうためにすべきこと
    良質なAPIドキュメントを用意する
    APIを見つけやすくする
    再利用性 / 汎用性のあるAPIを用意する
    API設計
    API設計 API構築
    API
    ディスカバリ
    API提供者として効率的、安定的、継続的に
    これらを提供していくことが重要

    View full-size slide

  9. APIを中心としたサービス戦略
    APIファースト戦略

    View full-size slide

  10. APIファーストの世界 https://api-first-world.com/ja/

    View full-size slide

  11. APIファースト戦略とは?
    ● APIに対する位置づけ、考え方
    ○ APIはプロダクト(主要ソフトウェア構成要素、主要ビジネスアセット)
    ○ APIがビジネスにもたらす価値に焦点を当てる
    ○ API中心:内外サービスをAPIを通じて活用しビルディングブロックで構築
    ● API開発モデル
    ○ APIを最優先に開発(APIを後回しにしない)
    ○ コードを書く前にAPIを設計・構築
    ● APIファースト採用のために必要な取り組み
    ○ APIライフサイクルを理解しライフサイクル全体で取り組む
    ○ APIの継続的な保守・運用のためのチーム体制を構築する
    API-First Guide https://www.postman.com/api-first/

    View full-size slide

  12. APIはプロダクト = 第一級市民
    ● APIは後付で構築するものではなく、最優先で構築するもの
    ● 戦略的なビジネスアセットとしてライフサイクル全体で管理する
    ● 一回きりのプロジェクトではなく、継続的に管理する
    ● 継続的な保守・運用のためのチーム体制を構築する

    View full-size slide

  13. Planning
    Defining
    Designing
    Building
    Testing
    Deployment
    SDLC
    (Software Development Life Cycle)

    View full-size slide

  14. API提供者と利用者のAPI開発ライフサイクル

    View full-size slide

  15. コードを書く前にAPIを設計・構築するとは?
    要件
    API設計
    コード
    API Spec作成
    APIドキュメント作成
    モック作成
    テストコード作成
    API定義・生成 テスト
    モック、テスト結果を元にレビューや
    フィードバックを受け設計内容を洗練させ
    る作業を繰り返す

    View full-size slide

  16. モックサーバー - モック用サービス
    実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成さ
    れ専用URLが発行される(デフォルトパブリックでプライベート設定可能) 。API 実装との依存関係が分離され、
    他のチームの作業から独立して作業を進めることができる
    Service A
    Service B
    Service C
    API
    未完成
    依存
    箇所
    依存
    箇所
    モック
    サーバー
    @postman_japan
    モックテスト

    View full-size slide

  17. API設計の指針
    ● ユーザーファースト
    ○ API設計をユーザーの視点から行う
    ● RESTful原則の遵守
    ○ リソース、エンドポイント、HTTPメソッドなど
    ● エラーハンドリング
    ○ エラーハンドリングの仕組み、一貫性のあるエラーコードやメッ
    セージ、適切なステータスコード
    ● バージョニング
    ○ しっかりバージョン管理、互換性を維持
    ● セキュリティ
    ○ 適切な認証・認可メカニズムの導入やデータの暗号化、など
    ● 性能と拡張性
    ○ リクエストとレスポンス最適化、キャッシング戦略、など
    ● 明確なAPI仕様と詳細ドキュメント
    ● Microsoft learn: RESTful Web API の設計
    ● 政府CIOポータル: APIテクニカルガイドブック

    View full-size slide

  18. API 仕様からドキュメント、モックの生成
    OpenAPI ツール群
    https://tools.openapis.org/
    例えば次のようなツールを使えば実現できます
    Postman
    https://postman.com

    View full-size slide

  19. 2つのAPI開発モデルを比較
    要件 要件
    コード API設計
    API
    Docs / Tests
    コード
    Comment
    Annotation
    API Spec
    API Docs
    API Mock
    API Tests
    コードファースト APIファースト

    View full-size slide

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

    View full-size slide

  21. APIファースト開発モデル
    ポイント
    ● APIコードを書く前にAPIを設計・構築
    ● API設計フェーズでフィードバックループを通じて設計内容を洗
    練化
    メリット
    ● 設計品質、開発者エクスペリエンス向上
    ● 要件・設計などの問題について早期発見ができ、変更コストが低いうちに変
    更、方向転換ができる。不確実性に対して柔軟。
    ● 設計段階で、APIドキュメントやテスト生成され、比較的初期段階でも関係
    者間でコラボレーションが可能
    デメリット
    ● 設計フェーズに時間がかかる
    ● 要件の変更に対する対応に時間がかかりがち(設計から入るため)
    要件
    コード
    API設計

    View full-size slide

  22. 利用者がAPIを見つけやすくするための活動

    View full-size slide

  23. 利用者がAPIを見つけやすくするための活動
    ● API仕様書、ドキュメントの公開
    ● デベロッパーポータルの構築・公開
    ● APIディスカバリプラットフォームの活用
    ○ APIマーケットプレイス

    View full-size slide

  24. APIファースト戦略 Recap
    ● APIに対する位置づけ、考え方
    ○ APIはプロダクト(主要ソフトウェア構成要素、主要ビジネスアセット)
    ○ APIがビジネスにもたらす価値に焦点を当てる
    ○ API中心:内外サービスをAPIを通じて活用しビルディングブロックで構築
    ● API開発モデル
    ○ APIを最優先に開発(APIを後回しにしない)
    ○ コードを書く前にAPIを設計・構築
    ● APIファースト採用のために必要な取り組み
    ○ APIライフサイクルを理解しライフサイクル全体で取り組む
    ○ APIの継続的な保守・運用のためのチーム体制を構築する
    API-First Guide https://www.postman.com/api-first/
    再掲

    View full-size slide

  25. APIファースト戦略 Recap
    良質なAPIドキュメントを用意する
    APIを見つけやすくする
    再利用性 / 汎用性のあるAPIを用意する
    API設計
    API設計 API構築
    API
    ディスカバリ
    効率的、安定的、継続的なAPIサービスの提供
    API
    ライフサイクル全

    View full-size slide

  26. PostmanはAPIファースト開発
    の実践をサポートする
    APIプラットフォーム

    View full-size slide

  27. Postmanが支援するAPI提供者と利用者両方の
    API開発ライフサイクル
    提供者・利用者間
    コラボレーション
    API提供者
    コラボレーション
    API利用者
    コラボレーション

    View full-size slide

  28. API設計支援ツール - APIビルダー
    OpenAPI
    Postman Collection
    RAML
    WSDL
    GraphQL
    ProtoBuf
    チームによるAPI設計を支援するツールです。直感的なUIを介してAPIの構造を定義できます
    APIビルダーの主要機能
    ● API設計
    ○ スキーマ定義(インポートも可能)
    ○ API定義のバリデーション
    ○ 定義からサーバーコード生成
    ○ テスト、ドキュメント生成
    ○ コレクション生成
    ● チーム開発支援
    ○ チーム間のAPI共有
    ○ コメント、Changelog
    ● APIバージョン管理
    ○ コードリポジトリ(GitHub, GitLab,
    Bitbucket, and Azure)と同期
    API設計

    View full-size slide

  29. Postmanスクリプトでテストや自動化を記述
    ● Postman サンドボックスで実行
    ● Built-inのJavaScript APIをpm、postmanオブジェクトを通じて利用可能
    ● Mochaベースのテストフレームワークを利用、AssertionライブラリとしてChaiが利用可能
    ● 豊富なスニペットとサンプルスクリプト集が用意されている
    ● 新機能: Postbot(AIを活用したスクリプト生成アシスタント)
    スクリプト
    Postbot
    スニペット
    ローコード
    支援機能
    テスト

    View full-size slide

  30. 生成AIを活用したテストコード生成 - Postbot
    https://blog.postman.com/meet-postbot-postmans-new-ai-assistant/
    テスト

    View full-size slide

  31. モックサーバー - モック用サービス
    実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成さ
    れ専用URLが発行される(デフォルトパブリックでプライベート設定可能) 。API 実装との依存関係が分離され、
    他のチームの作業から独立して作業を進めることができる
    Service A
    Service B
    Service C
    API
    未完成
    依存
    箇所
    依存
    箇所
    モック
    サーバー
    @postman_japan
    モックテスト

    View full-size slide

  32. コレクションランナーで複数リクエストのテスト実行
    実行
    実行結果詳細表示
    サマリー結果表示
    順番入れ替え可能
    実行方法選択
    手動 / スケジュール実行
    イテレーション数
    遅延秒数
    データファイル
    指定可能
    選択
    コレクションメニュー コレクションランナー実行方法設定
    テスト

    View full-size slide

  33. モニターで複数エリアから定期的にAPIテスト実行
    ● コレクションごとにモニターを設定
    ● テスト実行頻度
    ○ 5分毎〜設定可能。ただし無料プランは一時間毎〜
    ● テスト実行リージョン選択
    ○ 複数リージョンからの APIテスト実行が可能
    ● スタティックIPを持つモニター指定
    ○ 要Professional / Enterpriseプラン
    ● アラート通知設定
    ○ メール通知、or インテグレーション設定 でslack、
    PagerDutyなど他チャンネルへの通知も可能
    ● リトライ、タイムアウトなど設定可能
    リクエスト元リージョンの選択
    https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/
    監視・観測

    View full-size slide

  34. Postmanパフォーマンステスト
    コレクションもしくはフォルダーに登録されているAPIリクエスト群に対して、手軽にAPIクライアントから負
    荷をかけ、APIの性能フィードバックをリアルタイムで得られる機能
    実行
    コレクションランナー実行タイプ設定
    テスト (非機能要件)

    View full-size slide

  35. CLIを活用したCI/CD、継続的なテスト実行
    GitHub ActionsでのPostmanテストの実行イメージ
    Postman CLI からのコレクションテスト実行
    テスト

    View full-size slide

  36. 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/
    テスト (非機能要件)

    View full-size slide

  37. コラボレーション - APIの共同開発
    コラボレーション
    異なるアクセスレベルを設定可能なワークスペースと、その配下のコレクション、API定義、環境、モック、モ
    ニターなどを通じて、組織や世界をまたいだシームレスなコラボレーションを支援
    5つのアクセス共有レベル
    ● パーソナル
    ● プライベート
    ● チーム
    ● パートナー
    ● パブリック

    View full-size slide

  38. コラボレーション - APIの共同開発
    コラボレーション

    View full-size slide

  39. Postman APIネットワーク - APIの発見・探索・共有
    Postman API ネットワークは、 API 利用者と API 提供者の双方が API を簡単に発見、探索、共有でき
    るユニークな場所を提供します。
    Postman API ネットワークには2つの種類があります:
    パブリック
    APIネットワーク
    プライベート
    APIネットワーク
    APIネットワーク
    ディスカバリ

    View full-size slide

  40. パブリックAPIネットワーク
    パブリックAPIネットワークは、あらゆる利用者に公開されているAPIが含まれる世界最大規模のパブリッ
    クAPI成果物のカタログです。パブリックワークスペースを通じて組織のパブリック API を簡単に共有し
    たり、Salesforce、Paypal、Notion のような企業の何千ものパブリック API を発見したりすることがで
    きます。
    ● 広範な利用者・開発者へのアクセス
    ● 利用者のTime to first callの短縮化
    ○ 利用者は公開されているコレクションを
    Forkして利用
    ○ 利用者のAPIテストが容易になる
    ● 利用者からのフィードバックと改善
    ディスカバリ
    2023年9月〜
    日本語検索サポート

    View full-size slide

  41. プライベートAPIネットワーク
    プライベート API ネットワークは組織内のすべての内部APIをまとめている一元化された場所(内部APIカ
    タログ)であり、組織内の内部API成果物を簡単に発見、探索、共有ができます。
    これにより誰もが組織のAPIの全体像を把握できるようになるため、開発者と業務責任者の双方にとって
    メリットがあります。
    ● 組織内の機能重複の排除
    ● API知見・ノウハウの共有
    ● 組織内のAPI利用動向把握
    ● 利用者からのフィードバックと改善
    ディスカバリ

    View full-size slide

  42. 本セッションではAPIをもっと使ってもらうための選択肢の
    1つとしてAPIファースト戦略を紹介させていただきました。
    今後のAPI開発の参考になりましたら幸いです。
    ご清聴いただき、ありがとうございました。

    View full-size slide