Tweet
Tweet

Slide 1

Slide 1 text

インターフェース定義言語から学ぶ モダンな Web API 方式 REST, GraphQL, gRPC 1

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

私の仙台との接点 ( 仙台のイベント「タガヤス」ということで) 🐬は岐阜出身、千葉在住 2016 年4 月から ( 本社: 東京・市ヶ谷) 所属 2017 年からオプトの「仙台ラボラトリ」メンバー と合同で仕事することが増えた 2018 年春、2023 年春には仙台に出張する機会も 株式会社オプト 3

Slide 4

Slide 4 text

記事: サービス間連携のためのGraphQL API をClojure で開発している話 4

Slide 5

Slide 5 text

発表: at (2022-06-24) Java からScala 、そしてClojure へ: 実務で活きる 関数型プログラミング 【タガヤス その26 】初心者歓迎！関数型プログラ ミングって何だろう？ 5

Slide 6

Slide 6 text

Table of Contents 1. Web API のスキーマ駆動開発 2. 現代の主要なWeb API 方式 3. REST/GraphQL/gRPC のIDL 6

Slide 7

Slide 7 text

1. Web API のスキーマ駆動開発 7

Slide 8

Slide 8 text

スキーマ駆動開発 (schema-driven development) Web API のサーバとクライアントの間の「契約」で あるスキーマ(schema) を先行して定義し、それを 起点に実装を進める開発スタイル スキーマはインターフェース定義言語(inteface definition/description language; IDL) で記述する 認識齟齬/ 不整合を避けて効率的に開発できる コード/ ドキュメント生成などの応用もしやすい a.k.a. スキーマファースト開発(schema-first development) 8

Slide 9

Slide 9 text

スキーマ駆動開発 ( サーバサイド ) の基本的な流れ 1. API の構想/ 方式設計 2. API スキーマの( 初期) 設計 アウトプット: IDL ファイル 3. [optional] プロジェクト/ コードの自動生成 アウトプット: プロジェクトテンプレート/ スタ ブ/ 型定義コード 利用言語/ ライブラリ/ ツールに大きく依存する 4. API サーバ実装/ テスト ↺ API スキーマの拡張/ 修正 9

Slide 10

Slide 10 text

2. 現代の主要な Web API 方式 REST, GraphQL, gRPC 10

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

REST (representational state transfer) 本質: プロトコルに寄り添ったWeb API の設計 パターン 具体的な形式は設計者によって揺れが大きい: に基づいてYAML/JSON 形式 でスキーマを記述できる(de facto standard?) / の各種ツールでスキーマ編集/ 閲覧や動作確認、コード生成などができる e.g. ( ブラウザ版) HTTP Richardson Maturity Model OpenAPI Specification Swagger OpenAPI Swagger Editor 12

Slide 13

Slide 13 text

13

Slide 14

Slide 14 text

GraphQL 本質: クライアントに自由度を与えるWeb サービス のクエリ言語 cf. RDB に対するSQL ( 単純なREST API で発生しやすい) オーバーフェッ チング/ アンダーフェッチングを回避できる Schema Definition Language (SDL) でス キーマを記述する というブラウザIDE でAPI コールを試す ことができる e.g. GitHub GraphQL API の クライアントはGraphQL のクエリ言語を用いて必 要最小限のデータのみを選択的に取得できる GraphQL GraphiQL Explorer 14

Slide 15

Slide 15 text

15

Slide 16

Slide 16 text

gRPC 本質: ベースの効率的なRPC (remote procedure call) のためのフレームワーク マイクロサービスアーキテクチャのバックエンド サービス間連携で有力な選択肢 Web フロントエンド向けのAPI としても利用でき る: のIDL でスキーマを記述する (Protocol Buffers compiler) でサーバ/ ク ライアントのコード生成ができる ( バイナリ形式) でデー タを送受信する HTTP/2 grpc-web Protocol Buffers protoc Protocol Buffer wire format 16

Slide 17

Slide 17 text

17

Slide 18

Slide 18 text

3. REST/GraphQL/gRPC の IDL 18

Slide 19

Slide 19 text

インターフェース定義言語 (IDL) の記述 API style IDL REST OpenAPI Specification (.yaml, .json) GraphQL GraphQL SDL (.graphql) gRPC Protocol Buffers (.proto) 19

Slide 20

Slide 20 text

題材 : 蔵書 / 読書管理サービス cf. , 主な機能 カタログの書籍情報のCRUD 本棚( 蔵書) の書籍の読書状況/ レビュー情報の CRUD ※ サンプルコード: ブクログ 読書メーター web-api-style-comparison 20

Slide 21

Slide 21 text

[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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

[REST] 参照系操作の定義例 paths > /books > get: パス /books に対する GET リクエスト paths: /books: get: tags: - book_catalog summary: 書籍の一覧取得 operationId: get-books description: 検索条件を満たす書籍をカタログから取得する。 23

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

[REST] 更新系操作の定義例 paths > /books > post: パス /books に対す るPOST リクエスト paths: /books: post: tags: - book_catalog summary: 書籍の追加 operationId: post-books description: 書籍をカタログに追加する。 26

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

responses > '201': レスポンスステータスコー ド201 の場合 headers > Location: レスポンスのLocation ヘッダーの仕様 responses: '201': description: Created headers: Location: schema: type: string format: uri-reference example: /books/1 description: 追加された書籍へのURL 28

Slide 29

Slide 29 text

[GraphQL] データモデル ( エンティティ ) の定義例 Book データのオブジェクト型定義 T! はNon-Null 型( ただの T はnullable 型) """ 書籍""" type Book { """ 書籍ID""" id: ID! """ 書名""" title: String! """ 著者""" author: String! """ 出版社""" publisher: String! """ 出版年月日""" # ...( 中略)... """ レビューの集計結果""" reviewSummary: ReviewSummary! } 29

Slide 30

Slide 30 text

ReviewSummary, Review データのオブジェクト型 定義 [T] はList 型([T!], [T]!, [T!]! もある) """ レビューの集計結果""" type ReviewSummary { """ 平均ランク""" averageRank: Float """ リスト""" reviews: [Review!]! } """ レビュー""" type Review { """ ランク ( 星の数1 〜5)""" rank: Int """ コメント""" comment: String } 30

Slide 31

Slide 31 text

[GraphQL] 参照系操作の定義例 booksInCatalog クエリ(Query 型フィールド) の定義 type Query { """ カタログの書籍の一覧取得""" booksInCatalog( """ 書名 ( 部分一致)""" title: String """ 著者 ( 部分一致)""" author: String """ 出版社 ( 部分一致)""" publisher: String """ 出版年月日 ( 始点)""" publishedOnFrom: Date """ 出版年月日 ( 終点)""" publishedOnTo: Date ): [Book!]! } 31

Slide 32

Slide 32 text

[GraphQL] 更新系操作の定義例 addBookToCatalog ミューテーション(Mutation 型 フィールド) の定義 type Mutation { """ カタログへの書籍の追加""" addBookToCatalog( """ 追加内容""" input: AddBookToCatalogInput! ): AddBookToCatalogPayload } 32

Slide 33

Slide 33 text

addBookToCatalog ミューテーション用の入出力の 型定義 入力の型は input 、出力の型は type で定義す る input AddBookToCatalogInput { """ 書名""" title: String! """ 著者""" author: String! """ 出版社""" publisher: String! """ 出版年月日""" # ...( 以下略)... } type AddBookToCatalogPayload { """ 追加された書籍""" book: Book! } 33

Slide 34

Slide 34 text

[gRPC] データモデル ( エンティティ ) の定義例 Book データのメッセージ型定義 = の右辺のフィールド番号でフィールドが識別さ れる( ユニークに保ち、再利用しない) // 書籍 message Book { // 書籍ID int32 id = 1; // 書名 string title = 2; // 著者 string author = 3; // 出版社 string publisher = 4; // 出版年月日 /* ...( 中略)... */ // レビューの集計結果 ReviewSummary review_summary = 9; } 34

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

[gRPC] 参照系操作の定義例 BiblogApi サービスのListBooksInCatalog メソッド の定義 // 書籍管理サービス"Biblog" のgRPC API service BiblogApi { // 書籍を一覧取得する rpc ListBooksInCatalog(ListBooksInCatalogRequest) returns ( ListBooksInCatalogResponse); } 36

Slide 37

Slide 37 text

ListBooksInCatalog メソッド用の入出力の型定義 message ListBooksInCatalogRequest { // 書名 ( 部分一致) optional string title = 1; // 著者 ( 部分一致) optional string author = 2; // 出版社 ( 部分一致) optional string publisher = 3; // 出版年月日 ( 始点) /* ...( 以下略)... */ } message ListBooksInCatalogResponse { // 書籍のリスト repeated Book books = 1; } 37

Slide 38

Slide 38 text

[gRPC] 更新系操作の定義例 BiblogApi サービスのAddBookToCatalog メソッド の定義 // 書籍管理サービス"Biblog" のgRPC API service BiblogApi { // 書籍を追加する rpc AddBookToCatalog(AddBookToCatalogRequest) returns (AddB ookToCatalogResponse); } 38

Slide 39

Slide 39 text

AddBookToCatalog メソッド用の入出力の型定義 message AddBookToCatalogRequest { // 書名 string title = 1; // 著者 string author = 2; // 出版社 string publisher = 3; // 出版年月日 /* ...( 以下略)... */ } message AddBookToCatalogResponse { // 追加された書籍 Book book = 1; } 39

Slide 40

Slide 40 text

XaaS 時代の Web サービスのインターフェース (API) REST 以外の方式も選択肢として検討しよう スキーマ駆動開発を実践しよう 内部実装だけでなく設計について学ぼう 40

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

(REST) API とその設計 『Web API の設計』 『Web API: The Good Parts 』 『Web を支える技術 ―― HTTP ，URI ，HTML ，そ してREST 』 『API デザイン・パターン』 42

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

サンプルコード : 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