はてなサマーインターンシップ2025 Web API 講義資料

https://hatena.co.jp/recruit/intern/2025

Transcript

1. Web API IBUFOBJOUFSO !
2. ͜ͷߨٛͷ໨త • Web API を⽀えるプロトコル (HTTP) について知る • Web API の種類を知り、俯瞰できるようになる IBUFOBJOUFSO !
3. ϓϩτίϧ • = 約束ごと • TCP/IP, HTTP, DNS, TLS, SMTP, 3 • インターネットの参加者はプロトコルに従っている • サーバ（Google やはてな） • クライアント（ブラウザ、スマートフォンアプリ） • ルータ、… • これらのプロトコルは RFC によって定義される • = Request for Comments IBUFOBJOUFSO !
4. γϯλοΫεͱηϚϯςΟΫε • シンタックス（Syntax） • プロトコルの参加者が、どんなフォーマットでやりとりする か • セマンティクス（Semantics） • シンタックスに従ってやりとりされるデータをどう解釈する か IBUFOBJOUFSO !
5. HTTP Hypertext Transfer Protocol IBUFOBJOUFSO !
6. Hypertext Transfer Protocol http://www.example.com/ • ハイパーテキスト • リンクしたり画像を埋め込んだりできるテキスト • HTML によって表現されるもの • …のためのプロトコル IBUFOBJOUFSO !
7. HTTP ͷλΠϜϥΠϯ 1991 HTTP/%.' 1996 HTTP/%.' 1997 HTTP/%.% 2009 Google が SPDY を発表 2013 Google が QUIC を発表 2015 SPDY を元にしたHTTP/%の 標準化 2018 HTTP-over-QUIC を HTTP/%に改名 2021 QUIC の標準化 2022 HTTP/% の標準化 IBUFOBJOUFSO !
8. HTTP/1.1: HTTP ͷجૅ • RFC &''(: HTTP Semantics • RFC &''': HTTP Caching • RFC &''8: HTTP/'.' • Deprecated: • RFC 8(?@ Hypertext Transfer Protocol -- HTTP/'.' • RFC 8?'? Hypertext Transfer Protocol -- HTTP/'.' • RFC G8H( Hypertext Transfer Protocol (HTTP/'.'): Message Syntax and Routing • RFC G8H' Hypertext Transfer Protocol (HTTP/'.'): Semantics and Content • RFC G8H8 Hypertext Transfer Protocol (HTTP/'.'): Conditional Requests • RFC G8HH Hypertext Transfer Protocol (HTTP/'.'): Range Requests • RFC G8HN Hypertext Transfer Protocol (HTTP/'.'): Caching • RFC G8HO Hypertext Transfer Protocol (HTTP/'.'): Authentication IBUFOBJOUFSO !
9. Uniform Resource Locator (URL) • ブラウザで「開く」と… • HTTP(S) でリソースを取得する • motemen.hatenablog.com の 443 ポート • /search?q=git • データ (HTML) を解釈して表⽰する IBUFOBJOUFSO !
10. ਓؒ΋ HTTP/1.1 Λ஻ͬͯΈΔ • http://hatena.blog/ へのアクセス $ nc hatena.blog 80 GET / HTTP/1.1 Host: hatena.blog ↵ IBUFOBJOUFSO !"
11. HTTP/1.1 301 Moved Permanently Server: CloudFront Date: Mon, 28 Jul 2025 03:00:19 GMT Content-Type: text/html Content-Length: 167 Connection: keep-alive Location: https://hatena.blog/ X-Cache: Redirect from cloudfront Via: 1.1 0813d806b3dfe883cf8cfb0f711fd4ec.cloudfront.net (CloudFront) X-Amz-Cf-Pop: KIX56-P3 X-Amz-Cf-Id: -uMcBBc0Hyr2nrpWSAJZ4p-4mA8RPrzgM-t6SOUejkivv_ekknmmLA== <html> <head><title>301 Moved Permanently</title></head> <body> <center><h1>301 Moved Permanently</h1></center> <hr><center>CloudFront</center> </body> </html> IBUFOBJOUFSO !!
12. HTTPS ΋஻ͬͯΈΔ • HTTP over TLS • https://hatena.blog/ へのアクセス $ openssl s_client -connect hatena.blog:443 GET / HTTP/1.1 Host: hatena.blog ↵ IBUFOBJOUFSO !"
13. HTTP ͷεΠεΞʔϛʔφΠϑ: curl $ curl --head --location --verbose http://hatena.blog/ > HEAD / HTTP/1.1 > Host: hatena.blog > User-Agent: curl/8.7.1 > Accept: */* > < HTTP/1.1 301 Moved Permanently ... curl --help all で楽しもう IBUFOBJOUFSO !"
14. HTTP ͷηϚϯςΟΫε • リクエスト • メソッドとターゲット • レスポンス • ステータス • 共通 • ヘッダー • ボディ IBUFOBJOUFSO !"
15. HTTP/1.1 γϯλοΫε ϦΫΤετ <method> <target> HTTP/1.1 <field>: <value> <body> Ϩεϙϯε HTTP/1.1 000 <reason> <field>: <value> <body> IBUFOBJOUFSO !"
16. ϦΫΤετߦ <method> <target> HTTP/1.1 GET POST PUT HEAD DELETE OPTIONS TRACE CONNECT PATCH /entry/1 /search?q=text / HTTP/1.0 HTTP/1.1 IBUFOBJOUFSO !"
17. εςʔλεߦ HTTP/1.1 000 Reason • 1xx Informational • 2xx Successful • 3xx Redirection • 4xx Client Error • 5xx Server Error IBUFOBJOUFSO !"
18. ϘσΟ HTML <!DOCTYPE html> <html lang="ja"> ... JSON { "id": "42", "created": 1723707520, ... } PNG ը૾ ?PNG\0d\1a\00\00\00\0dIHDR... IBUFOBJOUFSO !"
19. ϔομʔ Host: hatena.blog Content-Type: text/html Content-Length: 167 Location: https://hatena.blog/ • メッセージを拡張したり、メタデータとして機能したり IBUFOBJOUFSO !"
20. Content-Type • Content-Type: text/html — HTML • Content-Type: application/json — JSON • Content-Type: image/png — PNG 画像 IBUFOBJOUFSO !"
21. ίϯςϯτωΰγΤʔγϣϯ 同じ URL へのアクセスでも… • Accept: text/html • リンク遷移など • Accept: image/* • <img> 要素からのリクエストなど IBUFOBJOUFSO !"
22. ϘσΟͷѹॖ • クライアント Accept-Encoding: gzip, deflate • サーバ Content-Encoding: gzip • gzip • compress • deflate • identity • br IBUFOBJOUFSO !!
23. ΫοΩʔ ! • サーバ Set-Cookie: key=value; Expires=Wed, 09 Jun 2024 10:18:14 GMT • クライアント Cookie: key=value • HTTP は本来ステートレス →「セッション」の導⼊ • ブラウザにクッキーを⾷べさせることで次回以降のリクエストに情 報を持ち越す IBUFOBJOUFSO !"
24. ೝূ ! Authorization: Basic xxxx Authorization: Bearer yyyy IBUFOBJOUFSO !"
25. Ωϟογϡ ! Cache-Control: public, max-age=14400 Cache-Control: private Vary: Accept-Encoding • 単体で RFC ができる程度には話題が多い • RFC 4555: HTTP Caching IBUFOBJOUFSO !"
26. HTTP/2 RFC %&'( Hypertext Transfer Protocol Version ; (HTTP/;) IBUFOBJOUFSO !"
27. HTTP/1.1 ͷ໰୊఺ • 背景: 複雑化する Web アプリケーション環境 • たくさんのアセット (JavaScript、画像、…) • モバイル機器からのアクセス • リクエスト-レスポンスのやりとりが TCP コネクションを専有 • ドメインあたりのコネクションは 6 つほどに制限されている • 「重い」リクエストがあると次のリクエストができない • ヘッダーの冗⻑性 IBUFOBJOUFSO !"
28. IBUFOBJOUFSO !"
29. HTTP/2 • セマンティクスは HTTP//./ と共通 • バイナリフレームでやりとり • ひとつの TCP コネクションを複数のストリームに分割 • 複数のリソースを⼀度にやり取りできる • 複雑な制御ができる • ヘッダーも圧縮 IBUFOBJOUFSO !"
30. HPACK RFC %&'( HPACK: Header Compression for HTTP/; Index Header Name Header Value / :authority 0 :method GET 1 :method POST 2 :path / 3 :path /index.html 4 :scheme http 5 :scheme https 6 :status 200 IBUFOBJOUFSO !"
31. HTTP/3 • QUIC トランスポート • UDP 上に TCP と TLS の機能を再現 • HTTP-over-QUIC • HTTP/B を QUIC トランスポート上で実装 • QPACK • コネクションマイグレーション $ open https://http3.is IBUFOBJOUFSO !"
32. HTTP • セマンティクス • HTTP/-.- • シンタックス • HTTP/2, HTTP/5 • モチベーション • 仕組み IBUFOBJOUFSO !"
33. API Application Programming Interface IBUFOBJOUFSO !!
34. Application Programming Interface • OS ⇔ アプリケーション • glibc: システムコール • ブラウザ ⇔ JavaScript アプリケーション • DOM (Document Object Model): HTML ⽂書を JS から操作 • Web サービス ⇔ Web フロントエンド、アプリ、別システム • REST • GraphQL • gRPC IBUFOBJOUFSO !"
35. LSUDs (Large Set of Unknown Developers) • 最⼤公約数的な API を提供する SSKDs (Small Set of Known Developers) • クライアントに最適化した API を提供する IBUFOBJOUFSO !"
36. API • REST • GraphQL • gRPC IBUFOBJOUFSO !"
37. REST Representational State Transfer • HTTP の仕組みをうまく使う • リソース指向 https://api.github.com/repos/hatena/example/issues/1 IBUFOBJOUFSO !"
38. CRUD HTTP メソッド Create POST Read GET Update PUT / PATCH Delete DELETE IBUFOBJOUFSO !"
39. ྫ: GitHub ͷΠγϡʔίϝϯτ • POST /repos/:owner/:repo/issues/:issue_number/comments • GET /repos/:owner/:repo/issues/comments/:comment_id • PATCH /repos/:owner/:repo/issues/comments/:comment_id • DELETE /repos/:owner/:repo/issues/comments/:comment_id IBUFOBJOUFSO !"
40. REST ͷΤϥʔϨεϙϯε • 厳密な制約はない • HTTP ステータスコードによる表現 • 例: レートリミットを超えた → 429 Too Many Requests • RFC TUVW: Problem Details • エラーレスポンスの形式を定める IBUFOBJOUFSO !"
41. OpenAPI • Swagger • REST API を記述するための仕様 • コード⽣成‧ドキュメント⽣成にも使える • 例: https://github.com/openai/openai-openapi IBUFOBJOUFSO !"
42. REST API ͷόʔδϣχϯά • path にバージョン番号を⼊れる • 例: X (旧 Twitter) • GET /A.A/statuses/show/:id • GET /G/tweets/:id IBUFOBJOUFSO !"
43. REST ͷಛ௃ • 実装や原則がシンプル • 道具なく作りはじめられる • REST「⾵」になりがちではある • Accidentally RESTful という表現もある • クライアント側から使いにくくなりがち • オーバーフェッチ、アンダーフェッチ • 要求の変化への対応が難しくなりがち IBUFOBJOUFSO !"
44. API • REST • GraphQL • gRPC IBUFOBJOUFSO !!
45. GraphQL • Facebook (現 Meta) によって開発された • クライアント側から必要なフィールドを指定する • スキーマからのコード⽣成ができる IBUFOBJOUFSO !"
46. SDL (Schema Definition Language) type Query { blog(id: String!): Blog } type Blog { title: String! entries(first: Int!): [Entry!]! } type Entry { title: String! body: String! name: String @deprecated(reason: "Use `title`.") } IBUFOBJOUFSO !"
47. εΧϥʔܕ Int Float String Boolean ID 独⾃のスカラー型を定義することもできる IBUFOBJOUFSO !"
48. ΦϒδΣΫτܕ type Blog { title: String! entries(first: Int!): [Entry!]! } ! がつくと non-nullable [T] はリスト型 IBUFOBJOUFSO !"
49. interface interface Publication { body: String! } type Entry implements Publication { body: String! comments: [Comment!]! } type Page implements Publication { body: String! } IBUFOBJOUFSO !"
50. union union EntryOrPage = Entry | Page IBUFOBJOUFSO !"
51. Query type Query { blog(id: String!): Blog } • リソースを取得する IBUFOBJOUFSO !"
52. Mutation type Mutation { createBlog(input: CreateBlogInput!): Blog } input CreateBlogInput { title: String! } • リソースを更新する IBUFOBJOUFSO !"
53. Subscription type Subscription { entryPosted(blogId: ID!): Entry } • リソースに変更があったことをリアルタイムに受信する IBUFOBJOUFSO !"
54. ྫ: GitHub API ΁ͷΫΤϦ $ gh api graphql --verbose -f query='query { viewer { login repositories(last: 3, visibility: PUBLIC) { nodes { name } } } }' { "data": { "viewer": { "login": "utgwkk", "repositories": { "nodes": [ { "name": "20241217-sketch-mysql-and-goqu" }, { "name": "autonolint" }, { "name": "terraform-provider-aws" } ] } } } } IBUFOBJOUFSO !"
55. GraphQL εΩʔϚઃܭͷίπ • リソース間の関係を⾃然にたどれるようにする • Mutation が返す専⽤の型を導⼊する • GraphQL Server Specification に準拠する IBUFOBJOUFSO !!
56. Ϧιʔεؒͷؔ܎ΛࣗવʹͨͲΕΔΑ͏ʹ͢Δ type User { name: String! blogs: [Blog!]! } type Blog { entries(first: Int!): [Entry!]! } type Entry { body: String! comments(first: Int!): [Comment!]! } type Comment { body: String! user: User } IBUFOBJOUFSO !"
57. Mutation ͕ฦ͢ઐ༻ͷܕΛಋೖ͢Δ type Mutation { createBlog(input: CreateBlogInput!): CreateBlogPayload } type CreateBlogPayload { blog: Blog } • 更新対象のエンティティをまとめて返す • 付加情報を返す IBUFOBJOUFSO !"
58. GraphQL Server Specification • Relay がスキーマに要求する追加仕様 • Node インタフェース • リソースを ID で直接取得する • Connection • ページネーション (継ぎ⾜し読み込み) IBUFOBJOUFSO !"
59. Node ΠϯλϑΣʔε interface Node { id: ID! } type Query { node(id: ID!): Node } IBUFOBJOUFSO !"
60. Connection type EntryConnection { edges: [EntryEdge!]! pageInfo: PageInfo! } type EntryEdge { cursor: String! node: Entry! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } type Blog { entries( first: Int, last: Int, before: String, after: String, ): EntryConnection! } IBUFOBJOUFSO !"
61. GraphQL ͱޓ׵ੑ • クライアントが参照していないフィールドを⾃由に追加できる • Query/Mutation/Subscription も同様 • クライアントが参照しているフィールドを変更‧削除すると互 換性が壊れる • 型やフィールドを分ける • @deprecated を活⽤する IBUFOBJOUFSO !"
62. @deprecated directive type Entry { title: String! body: String! name: String @deprecated(reason: "Use `title`.") } IBUFOBJOUFSO !"
63. πʔϧηοτͷαϙʔτ • サーバ • スキーマからのコード⽣成 • リゾルバの実装 • クライアント • UI ライブラリとの連携 • 型定義の⽣成 • キャッシュの管理 • GraphiQL IBUFOBJOUFSO !"
64. GraphQL ͷಛ௃ • クライアントは必要⼗分なデータを取得できる • クライアントはスキーマに基づいてリクエストを組み⽴てる • サーバ側は複雑になりがち • N+N クエリ • Dataloader • ⾃由に書けすぎるので制限が必要 • クエリの複雑度に上限を設ける • Persisted Query • ログ‧トレーシング IBUFOBJOUFSO !"
65. API • REST • GraphQL • gRPC IBUFOBJOUFSO !"
66. gRPC • Google によって開発された • RPC (Remote Procedure Call) のためのシステム • 定義ファイルからのコード⽣成 • HTTP/S ベース • 双⽅向ストリーミングもサポート IBUFOBJOUFSO !!
67. Protocol Buffers • 構造化されたデータをシリアライズする仕組み • バイナリフォーマット • IDL (Interface Description Language) • .protoファイル • RPC をサポートしている IBUFOBJOUFSO !"
68. gRPC ͱ Protocol Buffers • gRPC = Protocol Buffers を使うプロトコル ではない • シリアライズ⽅式はなんでもいい • Protocol Buffers を使うと楽、ということは⾔及されている IBUFOBJOUFSO !"
69. syntax = "proto3"; package account; service Account { rpc Signup(SignupRequest) returns (SignupReply); } message SignupRequest { string name = 1; string password = 2; } message SignupReply { string token = 1; } IBUFOBJOUFSO !"
70. ϝοηʔδܕ message SignupRequest { string name = 1; string password = 2; } ϑΟʔϧυܕ ϑΟʔϧυ໊ = ϑΟʔϧυ൪߸; • フィールド番号が重要 IBUFOBJOUFSO !"
71. ޓ׵ੑ • フィールド番号 int32 old_field = 6 [deprecated = true]; reserved 2, 15, 9 to 11; reserved "foo", "bar"; IBUFOBJOUFSO !"
72. Protocol Buffers ͷόʔδϣχϯά パッケージ名によってバージョニングを実現 • 例: Firestore RPC API • google.firestore.v6 • google.firestore.v6beta6 IBUFOBJOUFSO !"
73. αʔϏεͱετϦʔϜ service RouteGuide { rpc GetFeature(Point) returns (Feature) {} rpc ListFeatures(Rectangle) returns (stream Feature) {} rpc RecordRoute(stream Point) returns (RouteSummary) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} } IBUFOBJOUFSO !"
74. RPC ͷछྨ (1) • Unary RPCs (SimpleRPC) • single request single response • シンプルな通信 • Server streaming RPC • クライアント側はすべてのメッセージを受信すると処理を完 了する IBUFOBJOUFSO !"
75. RPC ͷछྨ (2) • Client streaming RPC • クライアント側は複数のメッセージを送り単⼀のメッセージを受信する • Bidirectional streaming RPC • 双⽅向ストリーミングのこと • クライアント側とサーバー側のストリームは独⽴している • そのためそれぞれ任意の順序でメッセージの読み書きができる IBUFOBJOUFSO !"
76. gRPC ʹ͓͚Δ API ઃܭ CRUD + List • CreateEntity • GetEntity • UpdateEntity • DeleteEntity • ListEntities IBUFOBJOUFSO !"
77. API • いくつかの API について⾒てきた • REST • GraphQL • gRPC • 特徴とトレードオフを理解して使おう IBUFOBJOUFSO !!
78. ͓ΘΓ IBUFOBJOUFSO !"
79. ࢀߟࢿྉ IBUFOBJOUFSO !"
80. HTTP • HTTP の概要 - HTTP | MDN • HTTP の進化 - HTTP | MDN • Set-Cookie - HTTP | MDN • SameSite属性とCSRFとHSTS - Cookieの基礎知識からブラウザごとのエッ ジケースまでおさらいする - GMO Flatt Security Blog • Real World HTTP 第3版―歴史とコードに学ぶインターネットとウェブ技術 • Web配信の技術―HTTPキャッシュ‧リバースプロキシ‧CDNを活⽤する IBUFOBJOUFSO !"
81. REST • Fielding Dissertation: CHAPTER 8: Representational State Transfer (REST) • REST という概念が初めて提唱された論⽂ • GitHub REST API documentation - GitHub Docs • API Reference - OpenAI API • Web API: The Good Parts IBUFOBJOUFSO !"
82. GraphQL • GraphQL Specification (October 5657 Edition) • GraphQL Server Specification | Relay • Relayに学ぶGraphQLのスキーマ設計 - cockscomblog? • 初めての GraphQL―Webサービスを作って学ぶ新世代API IBUFOBJOUFSO !"
83. gRPC (Protocol Buffers) • Introduction to gRPC | gRPC • Language Guide (proto 7) | Protocol Buffers Documentation • gRPC over HTTPB • Cloud Firestore API | Google Cloud • HTTP/B と gRPC に対するよくある誤解。 - ねののお庭。 IBUFOBJOUFSO !"