インターフェース定義言語から学ぶモダンなWeb API方式: REST, GraphQL, gRPC12. REST (representational state transfer)
本質: プロトコルに寄り添ったWeb APIの設計
パターン
具体的な形式は設計者によって揺れが大きい:
に基づいてYAML/JSON形式
でスキーマを記述できる(de facto standard?)
/ の各種ツールでスキーマ編集/
閲覧や動作確認、コード生成などができる
e.g. (ブラウザ版)
HTTP
Richardson Maturity Model
OpenAPI Specification
Swagger OpenAPI
Swagger Editor
12
16. gRPC
本質: ベースの効率的なRPC (remote
procedure call)のためのフレームワーク
マイクロサービスアーキテクチャのバックエンド
サービス間連携で有力な選択肢
Webフロントエンド向けのAPIとしても利用でき
る:
のIDLでスキーマを記述する
(Protocol Buffers compiler)でサーバ/ク
ライアントのコード生成ができる
(バイナリ形式)でデー
タを送受信する
HTTP/2
grpc-web
Protocol Buffers
protoc
Protocol Buffer wire format
16
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
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