WEBの基礎
WEB APIとは？
- API = Application Programming Interface
- 異なるアプリケーションとアプリケーションが互いにプログラミングを通して機械的に通信してやり取りができるようにすること
- WEB APIを使うことでPCとスマホのどちらの環境でも簡単にサービスを展開することができる
WEB APIの種類
REST API ⇨ シンプル
- URLとメソッドでデータを扱うシンプルな仕組み
- 幅広い言語やツールでサポート
- 多くのWebサービスで最も一般的
- HTTPに測ったシンプル設計
GraphQL ⇨ 柔軟
- 1つのエンドポイントで完結
- 違う情報を効率よく取得できるが実装はやや複雑
- フロントエンドとサーバ間のやり取りを柔軟に最適化可能
gRPC ⇨ ハイパフォーマンス
- バイナリ形式で高速通信が可能
- 多言語間のデータ交換がしやすく高負荷分散システムにも強い
- 設定に手間はかかるがパフォーマンス重視の場面で力を発揮
HTTP
HTTPの基本
-
HTTPとは、「Hypertext Transfer Protocol（ハイパーテキスト・トランスファー・プロトコル）」の略で、ウェブ上でデータをやり取りするための通信規約（ルール）のこと
-
HTTPプロトコルとは、Web上でデータがやり取りされる際のルールを定めたもの
REST API
REST APIとは？
- REST = WEBが大規模に機能する要因を整理した"設計ガイドライン"
REST の制約
-
クライアント・サーバ : クライアントとサーバを分離することで関心を分離する
※クライアントは見た目(UI)にサーバはデータの保存と操作にそれぞれ責任を持つ -
ステートレス : リクエストは、必要な全ての情報を含んでいる
-
統一インターフェース : ルールを統一することで異なるアーキテクチャ間の通信を簡単にする
-
キャッシュ : レスポンスは、キャッシュ可能かどうかを示す
-
階層化システム : 各コンポーネントは、隣接する階層以外のコンポーネントを『見る』ことができない
-
コードオンデマンド(任意) : クライアントで実行可能なコードがクライアントの機能拡張を可能にする
WEB APIの基本設計
リソース指向の考え方
メソッド エンドポイント(URI)
GET /repos/{owner}/{repo}/branches
HTTPメソッド
- GET:リソースを取得する
- POST:リソースを新規作成する
- PUT:リソースを更新する
- PATCH:リソースを部分的に更新する
- DELETE:リソースを削除する
エンドポイント設計
- エンドポイントは小文字の英字を使う
- エンドポイントに日本語は使わない
- 複数単語を繋げる場合、ハイフン繋ぎが無難
例) CATEGORIES
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /categories | カテゴリ一覧を取得 |
| POST | /categories | 新しいカテゴリを作成 (管理者用) |
| GET | /categories/{categoryId} | カテゴリの詳細を取得 |
| PUT | /categories/{categoryId} | カテゴリの詳細を編集 (管理者用) |
| DELETE | /categories/{categoryId} | カテゴリの詳細を削除 (管理者用) |
| GET | /categories/{categoryId}/products | 特定カテゴリに属する商品の一覧を取得 |
※リソースを一位に特定する際にはエンドポイントにIDを追加する
リクエスト・レスポンスのデータ設計
- リクエスト・レスポンスデータともにJSONフォーマットで統一する
- 1つのレンポンスデータに全部の情報を入れようとしない
STATUS CODEの設計
- 2XX : 成功
- 3XX : リダイレクト
- 4XX : クライアントエラー(リクエストに問題)
- 5XX : サーバーエラー(サーバーに問題)
WEB APIとキャッシュ
| 説明 | |
|---|---|
| max-age=<秒数> | キャッシュの有効期限を秒単位で指定 |
| no-shote | キャッシュそのものを禁止 |
| no-cache | キャッシュされるが、使用前に必ずサーバーで再検証を行う |
| must-revalidate | キャッシュが期限切れの場合、必ずサーバーに再検証を要求する |
| state-while-revalidate=<秒数> | キャッシュが期限切れの場合でも、再検証中にそのキャッシュを利用可能な秒数を指定 |
| public | レスポンスを全てのキャッシュ(クライアント、プロシキ、CDNなど)で保存を可能にする |
| private | レスポンスをクライアント専用にし、中間キャッシュ(プロシキ、CDN)では保存不可にする |
| s-maxage | キャッシュの有効期限を秒単位で指定。中間キャッシュ向け |
WEB APIと認証
認証
- ユーザが誰であるかを証明すること
認可
- ユーザができる権限を管理すること
ページネーション
オフセット方式
- 何番目からのデータが必要か指定する方式
Good
- 実装が簡単
- ページ番号によるページ遷移UIと相性が良い
Bad
- ページ間のデータ整合性を保つのが困難
- データ量が多くなると処理が重くなる
/products?offset=10&limit=50
offset: 取得を開始する位置
limit: 取得するデータの件数
ページ指定方式
- 何ページ目のデータが必要か指定する方式
Good
- 実装が簡単
- ページ番号によるページ遷移UIと相性が良い
Bad
- ページ間のデータ整合性を保つのが困難
- データ量が多くなると処理が重くなる
/products?page=3&limit=50
page: 取得したいページ番号
limit: 取得するデータの件数
カーソル方式
Good
- データの整合性を保ちやすい
- データベースに効率的なクエリを発行できる
Bad
- (場合によって)クライアント側の実装が少し複雑
- 『ページ番号』でのアクセスが難しい
/products?cursor=abc&limit=50
cursor: 取得を開始する特定のデータ
limit: 取得するデータの件数
WEB APIの設計パターン
検索APIの設計
GET
- シンプルな検索条件
/products?q=Java&price_min=100
POST
- 複雑な検索条件を入れられる
/products/search
{
"q":"Java",
"price_min":100
}
非同期処理(時間がかかる処理)の設計
- 画面を離れると接続が切れてしまい、処理結果が受けれない
- HTTPタイムアウトで強制切断の可能性
- HTTP接続維持によるサーバーリソースの無駄遣い
OpenAPI
OpenAPI Specification(OAS)
- APIの仕様定義のフォーマット
- JSONまたはYAML形式
- エンドポイント、リクエスト/レスポンスのフォーマット、認証方法などを定義
スキーマ駆動開発
- スキーマ駆動開発では、OASから作成し、そこからクライアントやサーバーコードを作る
※ スキーマ = APIが満たす仕様定義書