Learning Modern Web API Styles from IDL: REST, GraphQL, gRPC

インターフェース定義言語から学ぶモダンなWeb API方式: REST, GraphQL, gRPC
インターフェース定義言語(IDL)に注目しながらREST, GraphQL, gRPCの基本を学ぼう!

Transcript

1. インターフェース定義言語から学ぶ モダンな Web API 方式 REST, GraphQL, gRPC 1
2. lagénorhynque 🐬カマイルカ (defprofile lagénorhynque :id @lagenorhynque :reading "/laʒenɔʁɛ̃k/" :aliases [" カマイルカ" " 🐬"] :languages [Java Clojure Haskell Python 日本語 English français русский] :interests [ プログラミング 語学/ 言語学 数学 法/ 政治 財務/ 会計] :job-roles [ エンジニアリングマネージャー ソフトウェアアーキテクト] :motto " 楽しく楽にクールにスマートに" 2
3. 私の仙台との接点 ( 仙台のイベント「タガヤス」ということで) 🐬は岐阜出身、千葉在住 2016 年4 月から ( 本社: 東京・市ヶ谷) 所属 2017 年からオプトの「仙台ラボラトリ」メンバー と合同で仕事することが増えた 2018 年春、2023 年春には仙台に出張する機会も 株式会社オプト 3
4. 記事: サービス間連携のためのGraphQL API をClojure で開発している話 4
5. 発表: at (2022-06-24) Java からScala 、そしてClojure へ: 実務で活きる 関数型プログラミング 【タガヤス その26 】初心者歓迎！関数型プログラ ミングって何だろう？ 5
6. Table of Contents 1. Web API のスキーマ駆動開発 2. 現代の主要なWeb API 方式 3. REST/GraphQL/gRPC のIDL 6
7. 1. Web API のスキーマ駆動開発 7
8. スキーマ駆動開発 (schema-driven development) Web API のサーバとクライアントの間の「契約」で あるスキーマ(schema) を先行して定義し、それを 起点に実装を進める開発スタイル スキーマはインターフェース定義言語(inteface definition/description language; IDL) で記述する 認識齟齬/ 不整合を避けて効率的に開発できる コード/ ドキュメント生成などの応用もしやすい a.k.a. スキーマファースト開発(schema-first development) 8
9. スキーマ駆動開発 ( サーバサイド ) の基本的な流れ 1. API の構想/ 方式設計 2. API スキーマの( 初期) 設計 アウトプット: IDL ファイル 3. [optional] プロジェクト/ コードの自動生成 アウトプット: プロジェクトテンプレート/ スタ ブ/ 型定義コード 利用言語/ ライブラリ/ ツールに大きく依存する 4. API サーバ実装/ テスト ↺ API スキーマの拡張/ 修正 9
10. 2. 現代の主要な Web API 方式 REST, GraphQL, gRPC 10
11. REST schema definition SDL (IDL) data format (text), etc. (text), etc. (binary) notes (tools) query language (compiler) HTTP/2 GraphQL gRPC OpenAPI Specification GraphQL Protocol Buffers JSON JSON Protocol Buffer wire format Swagger protoc 11
12. REST (representational state transfer) 本質: プロトコルに寄り添ったWeb API の設計 パターン 具体的な形式は設計者によって揺れが大きい: に基づいてYAML/JSON 形式 でスキーマを記述できる(de facto standard?) / の各種ツールでスキーマ編集/ 閲覧や動作確認、コード生成などができる e.g. ( ブラウザ版) HTTP Richardson Maturity Model OpenAPI Specification Swagger OpenAPI Swagger Editor 12
14. GraphQL 本質: クライアントに自由度を与えるWeb サービス のクエリ言語 cf. RDB に対するSQL ( 単純なREST API で発生しやすい) オーバーフェッ チング/ アンダーフェッチングを回避できる Schema Definition Language (SDL) でス キーマを記述する というブラウザIDE でAPI コールを試す ことができる e.g. GitHub GraphQL API の クライアントはGraphQL のクエリ言語を用いて必 要最小限のデータのみを選択的に取得できる GraphQL GraphiQL Explorer 14
16. gRPC 本質: ベースの効率的なRPC (remote procedure call) のためのフレームワーク マイクロサービスアーキテクチャのバックエンド サービス間連携で有力な選択肢 Web フロントエンド向けのAPI としても利用でき る: のIDL でスキーマを記述する (Protocol Buffers compiler) でサーバ/ ク ライアントのコード生成ができる ( バイナリ形式) でデー タを送受信する HTTP/2 grpc-web Protocol Buffers protoc Protocol Buffer wire format 16
18. 3. REST/GraphQL/gRPC の IDL 18
19. インターフェース定義言語 (IDL) の記述 API style IDL REST OpenAPI Specification (.yaml, .json) GraphQL GraphQL SDL (.graphql) gRPC Protocol Buffers (.proto) 19
20. 題材 : 蔵書 / 読書管理サービス cf. , 主な機能 カタログの書籍情報のCRUD 本棚( 蔵書) の書籍の読書状況/ レビュー情報の CRUD ※ サンプルコード: ブクログ 読書メーター web-api-style-comparison 20
21. [REST] データモデル ( エンティティ ) の定義例 components > schemas > Book: Book データ のJSON 仕様(cf. ) components: schemas: Book: title: Book type: object properties: id: type: integer description: 書籍ID minimum: 0 readOnly: true title: type: string description: 書名 # ...( 以下略)... JSON Schema 21
22. required: 必須のプロパティ example: データ例 required: - id - title - author # ...( 以下略)... description: 書籍 example: id: 1 title: Web API の設計 author: '( 著) Arnaud Lauret, ( 翻訳) 株式会社クイープ, ( 監 修) 株式会社クイープ' publisher: 翔泳社 publication_date: '2020-08-26' official_site_url: 'https://www.shoeisha.co.jp/book/ detail/9784798167015' 22
23. [REST] 参照系操作の定義例 paths > /books > get: パス /books に対する GET リクエスト paths: /books: get: tags: - book_catalog summary: 書籍の一覧取得 operationId: get-books description: 検索条件を満たす書籍をカタログから取得する。 23
24. parameters: パラメータの仕様 parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - schema: type: string minLength: 1 in: query name: title description: 書名 ( 部分一致) - schema: type: string minLength: 1 in: query # ...( 以下略)... 24
25. responses > '200': レスポンスステータスコー ド200 の場合 content > application/json: レスポンス ボディのJSON 仕様 responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Book' pagination: $ref: '#/components/schemas/Pagination' # ...( 以下略)... 25
26. [REST] 更新系操作の定義例 paths > /books > post: パス /books に対す るPOST リクエスト paths: /books: post: tags: - book_catalog summary: 書籍の追加 operationId: post-books description: 書籍をカタログに追加する。 26
27. requestBody > content > application/json: リクエストボディのJSON 仕 様 requestBody: content: application/json: schema: $ref: '#/components/schemas/Book' examples: example-1: value: title: Web API の設計 author: '( 著) Arnaud Lauret, ( 翻訳) 株式会社 クイープ, ( 監修) 株式会社クイープ' publisher: 翔泳社 publication_date: '2020-08-26' # ...( 以下略)... description: 書籍 27
28. responses > '201': レスポンスステータスコー ド201 の場合 headers > Location: レスポンスのLocation ヘッダーの仕様 responses: '201': description: Created headers: Location: schema: type: string format: uri-reference example: /books/1 description: 追加された書籍へのURL 28
29. [GraphQL] データモデル ( エンティティ ) の定義例 Book データのオブジェクト型定義 T! はNon-Null 型( ただの T はnullable 型) """ 書籍""" type Book { """ 書籍ID""" id: ID! """ 書名""" title: String! """ 著者""" author: String! """ 出版社""" publisher: String! """ 出版年月日""" # ...( 中略)... """ レビューの集計結果""" reviewSummary: ReviewSummary! } 29
30. ReviewSummary, Review データのオブジェクト型 定義 [T] はList 型([T!], [T]!, [T!]! もある) """ レビューの集計結果""" type ReviewSummary { """ 平均ランク""" averageRank: Float """ リスト""" reviews: [Review!]! } """ レビュー""" type Review { """ ランク ( 星の数1 〜5)""" rank: Int """ コメント""" comment: String } 30
31. [GraphQL] 参照系操作の定義例 booksInCatalog クエリ(Query 型フィールド) の定義 type Query { """ カタログの書籍の一覧取得""" booksInCatalog( """ 書名 ( 部分一致)""" title: String """ 著者 ( 部分一致)""" author: String """ 出版社 ( 部分一致)""" publisher: String """ 出版年月日 ( 始点)""" publishedOnFrom: Date """ 出版年月日 ( 終点)""" publishedOnTo: Date ): [Book!]! } 31
32. [GraphQL] 更新系操作の定義例 addBookToCatalog ミューテーション(Mutation 型 フィールド) の定義 type Mutation { """ カタログへの書籍の追加""" addBookToCatalog( """ 追加内容""" input: AddBookToCatalogInput! ): AddBookToCatalogPayload } 32
33. addBookToCatalog ミューテーション用の入出力の 型定義 入力の型は input 、出力の型は type で定義す る input AddBookToCatalogInput { """ 書名""" title: String! """ 著者""" author: String! """ 出版社""" publisher: String! """ 出版年月日""" # ...( 以下略)... } type AddBookToCatalogPayload { """ 追加された書籍""" book: Book! } 33
34. [gRPC] データモデル ( エンティティ ) の定義例 Book データのメッセージ型定義 = の右辺のフィールド番号でフィールドが識別さ れる( ユニークに保ち、再利用しない) // 書籍 message Book { // 書籍ID int32 id = 1; // 書名 string title = 2; // 著者 string author = 3; // 出版社 string publisher = 4; // 出版年月日 /* ...( 中略)... */ // レビューの集計結果 ReviewSummary review_summary = 9; } 34
35. ReviewSummary, Review データのメッセージ型定 義 optional は省略可能フィールド repeated は0 個以上の繰り返しフィールド // レビューの集計結果 message ReviewSummary { // 平均ランク optional float average_rank = 1; // リスト repeated Review reviews = 2; } // レビュー message Review { // ランク ( 星の数1 〜5) optional int32 rank = 1; // コメント optional string comment = 2; } 35
36. [gRPC] 参照系操作の定義例 BiblogApi サービスのListBooksInCatalog メソッド の定義 // 書籍管理サービス"Biblog" のgRPC API service BiblogApi { // 書籍を一覧取得する rpc ListBooksInCatalog(ListBooksInCatalogRequest) returns ( ListBooksInCatalogResponse); } 36
37. ListBooksInCatalog メソッド用の入出力の型定義 message ListBooksInCatalogRequest { // 書名 ( 部分一致) optional string title = 1; // 著者 ( 部分一致) optional string author = 2; // 出版社 ( 部分一致) optional string publisher = 3; // 出版年月日 ( 始点) /* ...( 以下略)... */ } message ListBooksInCatalogResponse { // 書籍のリスト repeated Book books = 1; } 37
38. [gRPC] 更新系操作の定義例 BiblogApi サービスのAddBookToCatalog メソッド の定義 // 書籍管理サービス"Biblog" のgRPC API service BiblogApi { // 書籍を追加する rpc AddBookToCatalog(AddBookToCatalogRequest) returns (AddB ookToCatalogResponse); } 38
39. AddBookToCatalog メソッド用の入出力の型定義 message AddBookToCatalogRequest { // 書名 string title = 1; // 著者 string author = 2; // 出版社 string publisher = 3; // 出版年月日 /* ...( 以下略)... */ } message AddBookToCatalogResponse { // 追加された書籍 Book book = 1; } 39
40. XaaS 時代の Web サービスのインターフェース (API) REST 以外の方式も選択肢として検討しよう スキーマ駆動開発を実践しよう 内部実装だけでなく設計について学ぼう 40
41. Further Reading 公式ドキュメント OpenAPI Initiative Getting Started | OpenAPI Documentation GraphQL | A query language for your API Introduction to GraphQL | GraphQL gRPC Introduction to gRPC | gRPC Overview | Protocol Buffers Documentation 41
42. (REST) API とその設計 『Web API の設計』 『Web API: The Good Parts 』 『Web を支える技術 ―― HTTP ，URI ，HTML ，そ してREST 』 『API デザイン・パターン』 42
43. GraphQL, gRPC 『初めてのGraphQL ――Web サービスを作って学 ぶ新世代API 』 GraphQL in Action How to GraphQL - The Fullstack Tutorial for GraphQL gRPC: Up and Running API 設計: gRPC 、OpenAPI 、REST の概要と、それ らを使用するタイミングを理解する | Google Cloud 公式ブログ 43
44. サンプルコード : REST API (Clojure) cf. : GraphQL API (Clojure) cf. : gRPC API (Clojure) cf. lagenorhynque/web-api-style-comparison lagenorhynque/clj-rest-api 『3 つのLisp 3 つの世界』( 電子版) lagenorhynque/aqoursql Clojure のLacinia でGraphQL API 開発してみた lagenorhynque/route-guide Clojure のProtojure でgRPC API 開発してみた 44