All rights reserved by Postman Inc Web API 学習ロードマップ 2024 川崎庸市 Postman株式会社 Presentation slides for Postman Tokyo Meetup 2024.01

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

アジェンダ ● イントロ ● ここだけは押さえておきたいWeb APIの基礎 ● Web API学習ロードマップ ● おすすめ学習教材・リソース

API Application Programming Interface APIとはインターフェース @postman_japan

どんなインターフェース？ API提供者とAPI利用者とのやりとりをHTTP/HTTPSベースで実現するインターフェース API利用者 API提供者 API サービスを 提供したい サービスを 使いたい ルールに従い提供者と 利用者をつなぐ インターフェース @postman_japan

レストラン注文の例 お客様 （開発者） キッチン （アプリケーション） API 料理を提供 したい 注文したい ウェイター @postman_japan メニュー リクエスト リクエスト レスポンス レスポンス

テクノロジーの普及とAPI ● モバイル、クラウドコンピューティング、クラウドネイティブ技術 ● マイクロサービスアーキテクチャ、イベント駆動アーキテクチャ ● GraphQL ● AIと機械学習 ● 5G技術とIoT これらの普及により、APIの重要性が増している

ここだけは押さえておきたい Web APIの基礎

HTTP = 通信プロトコル ● OSI参照モデル、TCP/IPモデルの中のアプリケーション層に所属 ● HTTPはTCP/IP (インターネット基盤プロトコル)をベースにアプリレベルでデータ（メッセージ）のやり 取りを行う OSI model vs TCP/IP model https://stackoverflow.com/questions/38596488/in-which-layer-is-http-in-the-osi-model @postman_japan OSI参照モデル 各レイヤーのプロトコル TCP/IPモデル

HTTPには複数のバージョンがある ● HTTP/0.9 - 初期バージョン ○ ヘッダのないテキスト形式のワンラインプロトコル ● HTTP/1.0 - 拡張性を築く ○ 1991〜95に試行錯誤で、96年に正式発行 ● HTTP/1.1 - 標準化されたプロトコル ○ 1997年に初版、2014年に改訂版発行 ○ 同じくテキストメッセージ形式で、世界のほとんどのHTTPライブラリはHTTP/1.1をサポート ● HTTP/2.0 - 高パフォーマンスプロトコル ○ テキスト形式ではなくバイナリ形式（メッセージをフレームに分割して定義） ○ 同一接続で並行リクエストなど高速化のためHTTP/1.1の制約を排除 ● HTTP/3 - HTTP over QUIC（Quick UDP Internet Connections） ○ HTTP/2同様にバイナリ形式（メッセージをフレームに分割して定義） ○ UDPベースで、データを高速かつセキュアに転送するためのプロトコル ○ 全ウェブにおけるシェア拡大中（2024/01時点で28%強） HTTPの進化 https://developer.mozilla.org/ja/docs/Web/HTTP/Basics_of_HTTP/Evolution_of_HTTP @postman_japan

HTTPメッセージの構造（HTTP/1.1） 開始行 ヘッダー ボディ 空行 API利用者 （クライアント） HTTPメッセージ リクエスト レスポンス APIサーバー @postman_japan https://developer.mozilla.org/ja/docs/Web/HTTP/Messages

HTTPメッセージの構造（HTTP/1.1） 開始行 ヘッダー ボディ 空行 リクエスト行 GET /path HTTP/1.1 リクエスト ヘッダー リクエスト ボディ 空行 ステータス行 HTTP/1.1 200 OK レスポンス ヘッダー レスポンス ボディ 空行 基本構造 リクエスト レスポンス https://developer.mozilla.org/ja/docs/Web/HTTP/Messages @postman_japan

HTTPメッセージの構造（HTTP/1.1） HTTPリクエスト ● リクエスト行 ● ヘッダー（省略可） ● ボディ（省略可） HTTPレスポンス ● ステータス行 ● ヘッダー ● ボディ (省略可) https://postman-echo.com/get HTTP リクエスト HTTP レスポンス ヘッダー ヘッダー ボディ ステータス行 リクエスト行 HTTPメソッド HTTPステータス @postman_japan

メッセージ vs. フレーム ● HTTP/1.1 およびそれより前のバージョンのプロトコルでは、メッセージがコネクション内でそのまま送信 ● HTTP/2 では、人間が読める形式のメッセージを HTTP フレームに分割して、最適化やパフォーマンスの向上を実現 MDN HTTPメッセージ https://developer.mozilla.org/ja/docs/Web/HTTP/Messages [互換性] HTTP/2 のバイナリーフレーム化方式は、既 存のAPI や設定ファイルの変更を必要としないように 設計されていて、ユーザーに対しては透過的 参考情報

HTTPメソッド リソース操作のためのアクション / 動詞 メソッド名 説明 GET リソースの取得 POST リソースの登録（リソース名指定しない） POST: /book PUT リソースの登録/更新（リソース名指定） PUT: /book/1234 DELETE リソースの削除 PATCH リソースの一部変更 （vs. PUTは完全上書き、PATCHは一部） HEAD リソースのメタ情報の取得 OPTIONS リソースがサポートしているメソッドを調べる @postman_japan

HTTPヘッダー さまざまな種類のヘッダーがあります Mozilla mdn web docs HTTPヘッダー https://developer.mozilla.org/ja/docs/Web/HTTP/Headers ● 認証 ● キャッシュ ● クライアントヒント ● 条件付き ● 接続管理 ● コンテンツネゴシエーション ● 制御 ● クッキー ● CORS ● メッセージ本文の情報 ● プロキシー ● リダイレクト ● ダウンロード ● リクエストコンテキスト ● レスポンスコンテキスト ● 範囲付きリクエスト ● セキュリティ ● メタデータ読み取りリクエストヘッダー ● サーバー送信イベント ● 転送エンコーディング ● WebSocket ● その他 @postman_japan

HTTPステータスコード ● 1xx (情報レスポンス) ○ リクエストは受信され、その処理は継続中にある。 ● 2xx (成功レスポンス) ○ リクエストは、成功 ● 3xx (リダイレクト メッセージ) ○ リクエストを完了するには、更なる動作がとられる必要がある ● 4xx (クライアントエラー) ○ リクエストは不良な構文を包含しているか , または処理できない ● 5xx (サーバーエラー) ○ リクエストは受診されたがサーバはその処理に失敗した。 100 (Continue) 101 (Switching Protocols) 200 (OK) 201 (Created) 202 (Accepted) 203 (Non-Authoritative Information) 204 (No Content) 205 (Reset Content) 206 (Partial Content) [RFC7233] 300 (Multiple Choices) 301 (Moved Permanently) 302 (Found) 303 (See Other) 304 (Not Modified) [RFC7232] 305 (Use Proxy) 307 (Temporary Redirect) 400 (Bad Request) 401 (Unauthorized) [RFC7235] 402 (Payment Required) 403 (Forbidden) 404 (Not Found) 405 (Method Not Allowed) 406 (Not Acceptable) 407 (Proxy Authentication Required) [RFC7235] 408 (Request Timeout) 409 (Conflict) 410 (Gone) 411 (Length Required) 412 (Precondition Failed) [RFC7232] 413 (Payload Too Large) 414 (URI Too Long) 415 (Unsupported Media Type) 416 (Range Not Satisfiable) [RFC7233] 417 (Expectation Failed) 426 (Upgrade Required) 500 (Internal Server Error) 501 (Not Implemented) 502 (Bad Gateway) 503 (Service Unavailable) 504 (Gateway Timeout) 505 (HTTP Version Not Supported) https://developer.mozilla.org/ja/docs/Web/HTTP/Status @postman_japan

REST APIとは？ HTTPをベースにしたAPIアーキテクチャスタイルの１つ @postman_japan REST Webhook GraphQL SOAP Websockets gPRC MQTT AMQP SSE EDI EDA 2023年 API アーキテクチャスタイルの利用率 https://www.postman.com/state-of-api/api-technologies

RESTful API - Representational State Transfer 2000年にHTTP仕様の策定にかかわった一人であるRoy Fielding氏の論文で初めて使われた言葉 RESTの原則（Wikipedia） ● ステートレスなクライアント／サーバプロトコル ○ HTTPメッセージ一つ一つが、リクエスト（メッセージ）を理解するために必要な全ての情報を含む ○ 実際には多くのHTTPベースのアプリはCookieやセッション保持の仕組みを利用 ● すべての情報（リソース）に適用できる「よく定義された操作」のセット ○ メソッド（GET、POST、PUT、DELETE、etc.）を活用してリソース操作 ● リソースを一意に識別する「汎用的な構文」 ○ すべてのリソースはURI（Uniform Resource Identifier）で表される一意なアドレスを持つ ● アプリケーションの情報と状態遷移の両方を扱うことができる「ハイパーメディアの使用」 ○ 簡易な XMLやJSONを利用 ● Wikipedia: https://ja.wikipedia.org/wiki/Representational_State_Transfer ● Architectural Styles and the Design of Network-based Software Architectures https://ics.uci.edu/~fielding/pubs/dissertation/top.htm 参考情報

REST APIのアーキテクチャスタイルとは？ 以下の設計原則に基づいている ● リソース指向 ○ データはリソースとして表現して、一意のURIで識別 ○ （一般的に、データ形式にJSON、XMLを使用） ● HTTPメソッド = リソース操作のアクション ○ GETは取得、POSTは作成、PUTは更新、DELETEは削除 ● ステートレス性 ○ リクエストはステートレス ○ → リクエストには必要な情報が全て含まれているのでサーバーはクライアントの情報を保持し ない ● Wikipedia: https://ja.wikipedia.org/wiki/Representational_State_Transfer ● Architectural Styles and the Design of Network-based Software Architectures https://ics.uci.edu/~fielding/pubs/dissertation/top.htm @postman_japan

REST API - リソース指向とパラメータの使い分け パスパラメータとクエリパラメータ https://example.com/path/{path-param}?query={query-param} 使い分け例 ● 特定のリソースを識別する場合はパスパラメータ（リソース指向） ○ 例）https://example.com/product/1234 (商品IDが1234) ● リソース識別ではなく、条件追加などはクエリパラメータ ○ 例）https://example.com/search?q=postman (検索キーワードがpostman) @postman_japan

REST API - データ形式: JSON or XML ほとんどのケースでJSON 人間が読みやすく、コードでも操作しやすいデータ表現 @postman_japan { "members": { "member": { "no": 110, "name": "太郎さん", "addr": "東京都台東区 ", "addDay": "2024/01/29" } } } 110 太郎さん 東京都台東区 2024/01/29 JSON XML

Web API 学習ロードマップ

Web API学習ロードマップ Web API Web APIの基礎 認証/認可 APIアーキテクチャスタイル ベストプラクティス セキュリティ パフォーマンス最適化 実践的なツールの活用 HTTP基礎 データ形式 (JSON/XML) RESTful API原則 APIドキュメント(OpenAPI) 基本認証 / APIキー トークンベース認証 oAuth 2.0 OpenID Connect RESTful API Webhook/GraphQL/gRPC エラーハンドリング ページング/バージョニング セキュリティヘッダ / 暗号化 / レート制限 / OWASPリスク キャッシュ / 圧縮 / 接続再利用、など API Client (Postman, etc) Git/GitHub CI/CD テストツール 関連トピック

Developer Roadmap - Frontend & Backend https://roadmap.sh/frontend https://roadmap.sh/backend Frontend Backend 参考情報

おすすめ学習教材・リソース

おすすめ教材・リソース HTTPおよびWeb/Web API技術 ● MDNサイト: MDN Web docs - HTTP (Web技術全般。困ったときの参照先として) ● 書籍 Web API: The Good Parts (Web API基礎・設計・開発・運用。少々古いです) ● 書籍 Webを支える技術 (HTTP, URI, HTML, REST。少々古いです) REST API 設計ガイドライン ● Zalando: Zalando RESTful APIガイドライン ● Microsoftアーキテクチャセンター: RESTful Web API の設計

おすすめ教材・リソース Web API技術、およびPostman情報 ● Postman Japan Xアカウント @postman_japan ● Postman Meetup / ワークショップ https://postman.connpass.com/

本セッションでは、Web APIの基礎、学習ロードマップ、 参考教材について紹介させていただきました。今後の深い理解を 構築するための土台を築くきっかけになれば幸いです。 ご清聴いただき、ありがとうございました。