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

いまからでも遅くない!WebAPI超入門 座学編/dojo-20230427-webapibasic

HirokiK
April 27, 2023

いまからでも遅くない!WebAPI超入門 座学編/dojo-20230427-webapibasic

※本資料は以下のイベントの投影資料です
https://ibm-developer.connpass.com/event/278083/

いまやさまざまなところで使われているWebAPI。
例えば、自分の銀行口座の残高を見るときや、飛行機の予約をするときなど。
実は我々の生活のあちらこちらで使われています。エンジニアとしてみたとき
「仕組みってどうなっているんだろうか?」って気になりませんか?
今一度立ち止まって一緒にWebAPIについて、学んでみませんか?

本Dojoでは
「WebAPI?何それ美味しいの?」
「現場で使ってるけど、なんとなくで使ってる」
「APIとWebAPI違いよくわかってない。。」
「RESTFulとかいうんでしょ・・・?その辺フワッとしてます。。」
という方を対象とした、WebAPI初学者向けの内容になっています。

HirokiK

April 27, 2023
Tweet

More Decks by HirokiK

Other Decks in Technology

Transcript

  1. © 2023 IBM Corporation 2 ⾃⼰紹介 畠⼭ 健介 はたけやま けんすけ

    Automation-BA, Integration担当 Customer Success Manager 経歴 クラウドサービス企画/ローンチ、マネジャー 2017/10 IT製品ベンダーアカウントマネジャー 2007/4 ⾦融系基幹、周辺システム設計/構築/保守/改善 2005/4 Customer Success Manager Architect 2022/8 E-mail: [email protected]
  2. © 2023 IBM Corporation 3 免責事項 本資料に含まれる情報は可能な限り正確を期しておりますが、 記載された内容に関して、⽇本アイ・ビー・エム株式会社が 何ら保証するものではありません。 従って、本資料の情報の利⽤は使⽤者の責任において

    為されるものであり、資料の内容によって受けた 如何なる被害に関しても⼀切の補償をするものではありません。 [録画許可のお願い Dojoの様⼦を録画し、アーカイブとして公開させてください。 皆様のお顔、お名前は映らないように設定しています。
  3. © 2023 IBM Corporation 4 対象者と⽬的 • WebAPIという⾔葉を聞いたことがあるけど、何かを知らない⽅ • WebAPIをこれから学んでいきたい⽅

    WebAPIとは何か、またWebAPIに関連する内容も理解でき、これから ⾃⾝で学習を進められるようになる 対象者 ⽬的
  4. © 2023 IBM Corporation 5 アジェンダ 1. Web APIとは何か 2.

    HTTPプロトコルの基礎 3. RESTful APIの基礎 4. デモパート 5. まとめ
  5. © 2023 IBM Corporation 7 APIとは ・Application Programming Interfaceの略 ・ソフトウェアコンポーネント同⼠が互いに情報をやりとりするのに使⽤

    するインタフェースの仕様 (Wikipedia.「アプリケーションプログラミングインタフェース」. https://ja.wikipedia.org/wiki/アプリケーションプログラミングインタフェース(参照2023-03-13)) ・インタフェース:2つの異なる機器やシステム、ソフトウェア間で情報の やり取りがなされる際に、その間をつなぐ規格や機能を指す USBケーブル = インターフェース アプリの画⾯ = インターフェース
  6. © 2023 IBM Corporation 8 APIとは ・さらに、HTTP/HTTPSプロトコルを利⽤してネットワーク越しに呼び出すものを Web APIと呼びます。 ・(再掲)ソフトウェアコンポーネント同⼠が互いに情報をやりとりするのに

    使⽤するインタフェースの仕様 実⾏⽅法と実⾏されるサービスがわかれば 内部の処理の仕組みは知らなくても良い =APIのメリット API利⽤者 プログラム API提供者 プログラム API 内部処理 リクエスト レスポンス ショッピングサイト 決済するサイト
  7. © 2023 IBM Corporation 9 Web APIを利⽤するメリット・デメリット [メリット] ・⾃サービスの利便性の向上 ・低コストで機能が追加可能

    [デメリット] ・仕様変更や有料化、障害といった提供者側への依存の可能性 (アンドエンジニア.「 Web APIとは?仕組みや使い⽅、メリットをわかりやすく解説! 」. https://and-engineer.com/articles/Yw14sRAAACIA5tW0#heading2-3( 参照2023-03-13))
  8. © 2023 IBM Corporation 10 なぜAPIが注⽬されているか 「APIエコノミー」 Web APIを公開することで外部サービスとの連携を容易にして新たな価値が⽣まれ、サービスやビ ジネスが発展していくこと

    (⽔野貴明.「1.1.3 APIエコノミー」. 『Web API The Good Parts』. オライリー・ジャパン, 2014, p.7) ⾝近な例:Google Map レストラン評価サイトに、地図が埋め込まれている Programmable Web(世界的なAPIディレクトリのサイト)のファウンダーのJohn Musserは、APIの 公開はさまざまなサービスが相互に連携しつつ形成するサービスのエコシステムの中で”接着剤”の 働きをすると述べたといいます。 (⽔野貴明.「1.3.2 APIを公開することで得られるもの」. 『Web API The Good Parts』. オライリー・ジャパン, 2014, p.13) サービスを公開する⼒を持った開発者にAPIを公開することで、彼らがサービスに付加価値を与えて くれ、コアとなる⾃分たちのサービスがより発展する⼒をもらうことができる。 (⽔野貴明.「1.1 Web APIの重要性」. 『Web API The Good Parts』. オライリー・ジャパン, 2014, p.4)
  9. © 2023 IBM Corporation 13 HTTPプロトコルの概要 ・HTTP(Hypertext Transfer Protocol)とは、WebサーバとWebブラウザの間で、 Web情報をやり取りするためのプロトコル

    (通信規則) ・HTTPの特徴:動作がシンプル Webブラウザが要求(HTTPリクエスト)を出し、サーバが応答(HTTPレスポンス) を返します。この1つの要求には、1つの応答を返すルールになっています。 ①Webサーバに要求(HTTPリクエスト)を送る ②要求の処理を実⾏ ③処理結果の応答(HTTPレスポンス)を返す Webブラウザ Webサーバ
  10. © 2023 IBM Corporation 14 POST /api/users HTTP/1.1 Host: example.com

    Content-Type: application/json Authorization: Bearer abcdefg1234567890 { "name": "John Doe", "email": "[email protected]", "password": "secret" } HTTPリクエストの構造 HTTPリクエストは、クライアントがWebサーバに送信する情報のこと。 「リクエストライン、ヘッダ、ボディ」の要素で構成されています。 [HTTPリクエスト構成のサンプル] リクエストライン:HTTPメソッド、URI、プロトコル ヘッダ:HTTPリクエストのメタデータ ボディ:リクエストのデータ 例はJSON形式(後述)ですが、XMLなどその他形式である場合 もあります。
  11. © 2023 IBM Corporation 15 HTTPリクエストの構造 ・HTTPプロトコルで定義された、Webサーバーに対してクライアントが要求を⾏ うために使⽤されるコマンドのことです。 ・よく使われるものは以下の4つです。 HTTPメソッド

    説明 使⽤例 GET サーバからの情報の取得 ブラウザからのWebページの読み込み POST サーバへのデータ送信 フォームの⼊⼒情報の送信 PUT サーバ上のデータの更新 既存データの更新 DELETE サーバ上のデータの削除 不要データの削除
  12. © 2023 IBM Corporation 16 HTTPリクエスト/レスポンスの構造(JSON) ・JSON(JavaScript Object Notation)は、HTTPリクエスト/レスポンス のボディの要素で使われることが多いデータ形式です。

    { "name": "John Smith", "address": { "street": "123 Main St", "city": "Anytown” }, "phone_numbers": [ { "type": "home", "number": "555-555-1234” }, { "type": "work", "number": "555-555-5678" } ] } オブジェクト “key”: “value” の集合 配列。この例では2つのオブジェクトが要素。
  13. © 2023 IBM Corporation 17 ステータスコードの意味 HTTPリクエストが、正常に終了したかどうかを⽰すコード ・情報レスポンス(100-199) ・成功レスポンス(200-299) ・リダイレクトメッセージ(300-399)

    ・クライアントエラーレスポンス(400-499) ・サーバエラーレスポンス(500-599) 代表的なステータスコード: 200:OK リクエストが正常に終了した 404:Not Found リクエストのURLが解釈できなかった
  14. © 2023 IBM Corporation 19 RESTful APIの基本原則 ・シンプルなWebシステムの設計思想のこと REST(REpresentational State

    Transfer) RESTの4原則: ・統⼀インターフェース ・アドレス可能性 ・接続性 ・ステートレス性
  15. © 2023 IBM Corporation 20 RESTful APIの基本原則 ・統⼀インターフェース 「あらかじめ定義・共有された⽅法」で、やりとりすること ・アドレス可能性

    「すべての情報が、⼀意のURI(Uniform Resource Identifier)をもち、 提供する情報もURIで表現できる」こと ・接続性 「接続されているもの同⼠は、相互にリンク」していること ・ステートレス性 「状態を維持する仕組みを保持」しないこと
  16. © 2023 IBM Corporation 21 RESTful APIの基本原則 https://xxxx.comへ「/xxx/xx」の情報をリクエストします リンクを含んだ情報も返せます Webアプリ

    統⼀インターフェース HTTP アドレス可能性 URI 接続性 さっきの情報をもう⼀度欲しい さっきの情報はもう分かりません ステートレス性 サービス(プログラム) RES T
  17. © 2023 IBM Corporation 22 RESTful APIを利⽤する ・RESTful APIを利⽤するにあたって 1.

    リソースの決定: APIの利⽤者が、どのようなリソースを必要とするのか 2. リソースの操作法を確認 対象のリソースで、どのような操作ができるか リソースに必要な操作を、HTTPメソッドやURIなどで表現し、HTTPリクエストを発⾏ HTTPメソッド 説明 使⽤例 GET サーバからの情報の取得 ブラウザからのWebページの読み込み POST サーバへのデータ送信 フォームの⼊⼒情報の送信 PUT サーバ上のデータの更新 既存データの更新 DELETE サーバ上のデータの削除 不要データの削除
  18. © 2023 IBM Corporation 24 ⾃⼰紹介 北⽖ 裕紀 きたづめ ひろき

    Data&AI担当 Customer Success Manager Purpose お客様の挑戦を⽀え、寄り添うパートナーとなる 経歴 プロダクト開発マネジメント、社内向け情報発信 2020/4 ⾃社プラットフォームサービス企画提案 2018/11 エアライン系システム間通信開発、保守 2006/4 Customer Success Manager Architect 2022/7 Certified Scrum Product Owner Advocate IBM Cloud v2 HCD-Net ⼈間中⼼設計スペシャリスト E-mail: [email protected] LinkedIn: https://linkedin.com/in/hiroki-kitazume/
  19. © 2023 IBM Corporation 25 デモパート概要 • サンプルプログラムを元に、今までに学んだ基本的な概念が実際に動作するところ をご覧いただきます。 •

    サンプルプログラムはGitHubで公開しておりますので、お⼿元で動かしたり、Dojo の復習などにお役⽴てください。 https://github.com/IBMDeveloperTokyo/dojo-restapi-230427
  20. © 2023 IBM Corporation 26 実⾏環境 ・コンテナ:Podman 4.4.4 ・⾔語:Python 3.9.6

    ・Webアプリケーションフレームワーク:Django 4.2 ・インメモリデータベース:SQLite3 ・RESTful APIフレームワーク:Django REST framework 3.14.0 ローカル環境(Mac OS) APIクライアントツール (Visual Studio Code/ Thunder Client) コンテナ (Podman) アプリケーション API インメモリデータベース (SQLite3)
  21. © 2023 IBM Corporation 27 リソース説明 リソース名:UserInfo # フィールド名 データ型

    説明 制約 1 id Integer ⼀意なID ⾃動採番 2 user_name CharField ユーザ名 最⼤⻑32⽂字 3 member_since DateField ⼊会⽇ デフォルト値は現在時刻 4 membership_years Integer 会員年数 0以上の整数値、null許容 5 created_at DateTime Field UserInfoが 作成された⽇時 現在時刻を⾃動設定
  22. © 2023 IBM Corporation 29 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認
  23. © 2023 IBM Corporation 30 認証について ユーザを認証するために払い出した認証情報である⽂字列である「アクセストーク ン」をもって認証します。例えるならパスポートのようなもので、提⽰することでAPI を利⽤できるようになります。 より⾼度なセキュリティが要求される場合には、OIDCという認証プロトコルでの実装を推奨します。

    Step1.アクセストークンの発⾏ APIサーバ API Client ユーザ名/ パスワード アクセス トークン 発⾏⽤API 私のユーザ名/パスワードはxxxです。 アクセストークンをください Step2.その他APIの利⽤ APIサーバ API Client その他の API create APIを実⾏してください、 アクセストークンはこれです。 アクセストークンには有効期限があり、 超過したら取り直し。
  24. © 2023 IBM Corporation 31 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認 curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=user1&password=userpa22" http://localhost:8000/api/token/ -> “access”の値(アクセストークン)をメモ
  25. © 2023 IBM Corporation 32 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認 curl -X GET http://localhost:8000/api/userInfo/ -H "Authorization: Bearer <ACCESS_TOKEN>"
  26. © 2023 IBM Corporation 33 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認 curl -X POST http://localhost:8000/api/userInfo/ \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"user_name": "John Doe", "member_since": "1990-01-01", "membership_years": 33}ʼ curl -X GET http://localhost:8000/api/userInfo/ -H "Authorization: Bearer <ACCESS_TOKEN>"
  27. © 2023 IBM Corporation 34 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認 curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer <アクセストークン>" -d '{"user_name": "Taro Updated", "member_since": "1990-01-01","membership_years": 1}' http://localhost:8000/api/userInfo/3/ curl -X GET http://localhost:8000/api/userInfo/ -H "Authorization: Bearer <ACCESS_TOKEN>"
  28. © 2023 IBM Corporation 35 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認 curl -X DELETE -H "Authorization: Bearer <ACCESS_TOKEN>" http://localhost:8000/api/userInfo/3/ curl -X GET http://localhost:8000/api/userInfo/ -H "Authorization: Bearer <ACCESS_TOKEN>"
  29. © 2023 IBM Corporation 36 デモシナリオ 認証 アクセストークンの取得 create リソース作成

    update リソース更新 delete リソース削除 無効なリクエスト list 既存リソースの確認 ①認証エラー->401 Unauthorized curl -X GET http://localhost:8000/api/userInfo/ -H "Authorization: Bearer xxx" ②必須項⽬のuser_nameが存在しない->400 Bad Request curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" -d '{"member_since": "1990-01-01", "membership_years": 33}' http://localhost:8000/api/userInfo/
  30. © 2023 IBM Corporation 37 デモパートまとめ • リソース・APIの具体例を元に、REST APIによるリソースの基本操作を御覧いただ きました。

    • デモを通じて、 アクセストークンによる認証、 HTTPメソッドの使い分け、 リクエスト・レスポンスのフォーマット を学びました。
  31. © 2023 IBM Corporation 39 まとめ ・API(Application Programming Interface) ソフトウェアコンポーネント同⼠が互いに情報をやり取りするのに使⽤するインターフェースの仕様

    ・WebAPIと種類 WebAPIとは、HTTP/HTTPSプロトコルを介して、ネットワーク越しに呼び出すAPI 種類:RESTful API、SOAP API、GraphQL ・HTTP(Hypertext Transfer Protocol) WebサーバとWebブラウザの間で、Web情報をやり取りするためのプロトコル(通信規則) ・HTTPリクエスト クライアントからWebサーバに送信する情報のこと。「リクエストライン、ヘッダ、ボディ」の要素で構成 WebAPIを呼び出す際に使⽤
  32. © 2023 IBM Corporation 40 まとめ ・REST RESTの4原則に基づき、シンプルにアクセス、連携できる思想 「統⼀インターフェース、アドレス可能性、接続性、ステートレス性」 ・RESTful

    API RESTful APIは、RESTの4原則に基づいたWebAPI ・RESTful APIの使⽤ ①リソースを決定し、②リソースの操作法を確認(APIドキュメント)、 ③リソースの呼び出し(HTTPリクエスト)
  33. © 2023 IBM Corporation 42 当⽇いただいたご質問への回答 1 Q. WEB API(RESTful

    API)とMQTT APIの違いと使い分けを教えてください。 A. 使い分けの例としては、Web APIを使⽤して、ユーザーがWebアプリケーションから情報を取得する 場合や Webアプリケーションから外部のサービスにデータを送信する場合に使⽤します。 ⼀⽅、MQTT APIは、IoTデバイス間の通信や、デバイスからクラウドサービスへのデータ転送など軽 量なデータを扱う際に使⽤します。
  34. © 2023 IBM Corporation 43 当⽇いただいたご質問への回答 2 Q.先ほど説明のあった、API Documentationは何かのツールで作成しているんでしょうか?それとも コーディング作成後に⾃動出⼒されるものですか?

    A. APIドキュメント⽣成ツール「drf-yasg」というものを使⽤しています。 https://drf-yasg.readthedocs.io/en/stable/# こちらを利⽤することで、ソースコードからAPIの仕様を読み取り⾃動出⼒します。 また、API名やパラメータ名などに⾃⾝で説明を追加することもできます。
  35. © 2023 IBM Corporation 44 当⽇いただいたご質問への回答 3 Q.使⽤されていた VS Code

    のHTTP拡張機能の名前を教えていただけないでしょうか? A. Thunder Clientというものです。 https://www.thunderclient.com/
  36. © 2023 IBM Corporation 45 当⽇いただいたご質問への回答 4 Q. RESTful APIの設計(Request時のパラメータ名やResponse時のデータ形式)において、規約や、

    デファクトスタンダードの書き⽅のようなものはあるんでしょうか? A. URIの設計、HTTPメソッドの使い分け、リクエストパラメータの設計、レスポンスの設計 である程 度決まっているいるものもあります。 例えばレスポンスはJSONで返すのが⼀般的です。 リクエストパラメータは命名規則(キャメルケース、スネークケースなど)にも注意が必要です。こ れは会社やチームでのルールに従う必要があります。
  37. © 2023 IBM Corporation 46 未回答のご質問(2023/4/27) 以下の未回答のご質問について、追ってご回答しconnpassでご連絡いたします。 Q. RESTの4原則のアドレス可能性について、「HTTPリクエスト、レスポンスに対してURIで⼀意に 特定できること」と説明されていたように思いますが、これは後からHTTPリクエストを追跡するこ

    とができることを指していますか?URLによってアクセス対象のAPIが⼀意であることだけを指して いますか? Q. RESTの原則の接続性について、具体的にどういうことを指しているのか解説いただきたいです Q. 最近、ChatGPT-APIを利⽤しました。ChatGPT-APIはRESTful API SOAP API GraphQL の うちだとどれに属するものなのでしょうか。