ソニックの部屋

主にプログラミングに関する記事を投稿します

REST APIまとめ

気になった用語をまとめた

Webサービスの基本

  • WebAPIとは、HTTPなどのインターネット関連技術を利用してプログラムが読み書きしやすい形でメッセージ送受信を行えるよう定義した規約、または規約を実装して展開されるサービスのこと
  • リクエストの中でCRUDに相当するメソッド（POST、GET、PUT、DELETE）が重要
メソッド 意味
GET リソースの取得
POST リソースの新規登録(データ作成時にリソース名が決まっていない、決まっていればPUTになる)
PUT リソースの更新
DELETE リソースの削除
  • 冪等(べきとう)とは何度実行しても同じ状態が再現されること
  • データ登録（POST）は冪等ではない

REST制約

  • RESTとは設計ルールのこと
  • REST原則は6種類
原則 内容
クライアント/サーバー ・画面(クライアント)とデータ(サーバー)を分離
・トリガー(クライアント)と受け身(サーバー)
階層化システム WEB, AP, DBサーバーの多層アーキテクチャ構成
コードオンデマンド サーバー側を更新してもクライアント側で勝手にDLして新しい環境を手に入れる
統一インターフェース 4つの制約、例えばURIでリソース(サーバーに保存されたデータ)を識別する
ステートレス ・前の状態を保存せず単独で成り立つこと
・サーバーはリクエストだけでコンテキストを理解できる
キャッシュ機能 クライアントはレスポンスをキャッシュできる
  • REST API成熟モデルとは設計レベル4段階のこと(レベル0~3)
レベル 内容
3 レスポンスにリソース間のつながり(ハイパーリンク)を含める
2 一般的なREST。HTTPメソッドを活用。CRUD操作が可能
1 リソースごとにURLを分割。GET, POSTのみ使用
0 基本レベル。HTTPを使っている

REST WebAPIサービス設計(基本)

  • URIはリソースを表現するもの
  • URIは短く、人が読んで理解できる、全て小文字、単語はハイフンでつなげる、単語は複数形にする
ex.
GET http://api.example.com/users-tables/12345
  • URIはエンコードを必要とする文字を使わない、サーバー側のアーキテクチャを反映しない、改造しやすい、ルールが統一されている
  • HTTPメソッドをURIに適用するとは、URIは同じでHTTPメソッドを変えることで操作を変えること
ユーザー情報の取得：GET          http://api.example.com/users
ユーザーの新規登録：POST       http://api.example.com/users
  • リソースを特定するパラメータは2つ
クエリパラメーター：URLの末尾に？に続くキーバリュー
GET    http://api.example.com/users?**page=3**

パスパラメーター：URLの中に埋め込まれるパラメーター
GET    http://api.example.com/users/**123**
ステータスコード 意味
100 情報
200 成功
300 リダイレクト
400 クライアントサイドに起因するエラー
500 サーバーサイドに起因するエラー
  • レスポンスのデータフォーマットは3種類
レスポンス 特徴
XML タグ付きのテキスト形式
JSON ・キーバリューのテキスト形式
・XMLに比べてデータ量が減らせる
JSONP javascriptのテキスト形式
  • データフォーマットの指定方法
フォーマット 形式
クエリパラメータ http://~users?format=json
拡張子 http://~users.json
リクエストヘッダー GET http://~
Host: api.sample.com
Accept: application/json
設計上はおすすめ

  • データの内部構造について

    • エンベロープ(レスポンスボディ内のメタ情報)は使わない(ヘッダー情報と被るため)
    • オブジェクトはフラットにする(ネストさせない)
    • ページネーションをサポートする情報を返す(キーとなる情報を返す)
    • プロパティの命名規則は統一する(キャメルケースで統一するなど)
    • 日付はRFC3339形式を使う(インターネットでの標準形式)
    • 大きな数値は文字列で返す

  • エラーの詳細はレスポンスボディに入れる

  • エラーの際にHTMLが返らないようにする(application/jsonで返す)
  • サービス閉塞時は「503 + Retry-After」で返す

REST WebAPIサービス設計(応用)

  • 広く公開するサービスであればAPIバージョンを含めたURL設計を行う
  • バージョンを入れる箇所は3箇所
場所 例
パス http://~/v1/users/
クエリ http://~users?version=1
ヘッダー GET http://~
GData-Version(サービス固有の接頭辞をつける)
設計上はおすすめ
  • バージョンの付け方はセマンティックバージョニングとなる
  • バージョン：1(メジャー). 2(マイナー). 3(パッチ)
  • メジャーは後方互換しない修正
  • マイナーは後方互換する機能追加
  • パッチは後方互換するバグ修正
  • APIはメジャーのみ付けるのがおすすめ
  • 認証は「本人特定」、認可は「アクセス制御」
  • OAuthもOpenID Connectも認可の仕組み
  • OpenID ConnectはOAuthに本人情報取得を加えた仕組み
  • JSON Web Token(JWT)(ジョットと読む)、RFC7519で標準化、データの中身がJSON形式、認証結果をクライアントサイドで保持
  • JWTはセッションに保存するデータ
  • JWTは認証で利用するヘッダーであるAuthorizationヘッダーに埋め込んで利用する
  • WebアプリをAPI化すると簡単に大量アクセスするプログラムが書け、意図しない大量アクセスが発生する可能性がある
  • 対策としては時間あたりのアクセス制限をかける（＝レートリミット）
  • レートリミットの主要なアルゴリズムは3種類
  • キャッシュ制御に利用するヘッダーは2分類3パターン
Expires: Sun, 03 May 2020 12:30:00 GMT
・キャッシュとしていつまで利用可能かの期限を指定
Cashe-Control: public, max-age=604800
Date: Sun, 03 May 2020 12:30:00 GMT
・キャッシュの可否、期限を指定
・publicはどこでも保存できる
・max-ageはキャッシュ期限
Last-Modified: Sun, 03 May 2020 12:30:00 GMT
ETag: "4324k23h5h3j2g5hl3h53kj2h5"
・リソースの最終更新日時を指定
・特定バージョンを示す文字列を指定
  • APIはスマホアプリ、Webページ、バッチ(外部システム)などから呼ばれる
  • よってセキュリティ対策が必要
脆弱性 内容
XSS 悪意あるユーザーが正規のサイトに不正なスクリプトを挿入することで、正規ユーザーの情報を不正に引き出したり操作できてしまう問題
対策：レスポンスヘッダーの追加
CSRF 本来拒否しなければいけないアクセス元からくるリクエストを処理してしまう問題
対策：攻撃者に推測されにくいトークンの発行と照合処理を実装
HTTP 通信経路が暗号化されていないので盗聴されやすい
対策：HTTPSを利用する
HTTPSはSSL+TLS、SSL(2015年に廃止)、TLS(後継)は安全に通信を行うためのプロトコル
JWT クライアント側で内容の確認・編集が簡単にできるため、サーバー側の検証が不十分だと改ざんされた情報を正規として受け入れてしまう
対策：ヘッダーのalgに"none"以外を指定して署名を暗号化する

参考：課題

  • REST APIについて自分の言葉でまとめて提出すること
    • REST APIとは、RESTと呼ばれる設計ルールに基づいたインターネット通信の規約または規約を実装して展開されるサービスのこと
  • movieをリソースとして CRUD操作のURI、HTTPメソッドを定義して提出すること
URI HTTP method
GET http://api.example.com/movies GET
POST http://api.example.com/movies POST
PUT http://api.example.com/movies PUT
DELETE http://api.example.com/movies DELETE

参考文献
津郷 晶也, 2023, 「REST WebAPI サービス 設計」, udemy, （2023/9/19取得，https://www.udemy.com/）．