Skip to content

MS_REST

Jump to bottom
nishi_74322014 edited this page Aug 3, 2026 · 1 revision

REST

概要

JSONを返す WebAPI を、ざっくり REST API とか
言っているケースが多いので、定義を明らかにする。

広義

2000 年に Roy Fielding 氏が提唱した、分散システムにおいて
複数のソフトウェアを連携させるのに適した設計原則の集合（アーキテクチャ スタイル）。

狭義

上記の設計原則を Web に適用したソフトウェアの設計様式
（一般的には、コチラの狭義の意味が用いられている）。

一般によく使われる狭義のREST

  • パラメータを指定して特定の URL に HTTP でアクセスすると、
    JSON（、XML）で記述されたメッセージが送られてくるような
    WebAPI（「RESTful API」と呼ばれる）のことを指す。

  • 厳密な技術的定義が共有されているわけではなく、
    「RPC や SOAP などを必要としない、JSON（、XML）を返す WebAPI」
    くらいの意味で用いられる場合が多い。

RESTの設計原則（抽象的な概念）

Fielding 氏が示した REST の設計原則（抽象的な概念）。

  • セッションなどの状態管理を行わない。
    やり取りされる情報はそれ自体で完結して解釈することができる。

  • 情報を操作する命令の体系が予め定義・共有されている。
    HTTP の GET や POST などに相当。

  • すべての情報は汎用的な構文で一意に識別される。
    HTTP の URL や URI に相当。

  • 別の情報や、情報の別状態へのリンクを含めることができる。
    HTML や JSON、XML に相当。

理論上は HTTP や XML とはまったく無縁な REST システムもあり得る。

補足: Fielding 氏の原論文における制約は、正確には次の 6 つである （最後の 1 つは任意）。上記 4 点はこのうち 「ステートレス」「統一インターフェイス」の具体化にあたる。

  1. クライアント／サーバ
  2. ステートレス
  3. キャッシュ可能（→ キャッシュ・コントロールのHTTPヘッダ）
  4. 統一インターフェイス
  5. 階層化システム
  6. コード オン デマンド（任意）

なお 4 の「統一インターフェイス」には HATEOAS（レスポンスに次に辿れるリンクを含める）が含まれるが、 実際の RESTful API でこれを実装しているものは稀である。 「本当の REST ではない」という論争の火種は、ほぼここにある。

設計ポイント

REST は疎結合で、不特定多数の開発者を相手にする場合は優れた方法らしい。

コレを実現する REST の設計のポイントだが、ざっくり、
以下手順により、指定の URI で指定のリソースに対する操作を実現する。

  1. リソースを決定する。
  2. URI を決める。
  3. HTTP メソッドを決定する。
  4. リターンを決める。

・・・翌々見てみると、REST はデータ中心が過ぎるので、
機能中心の URI にしたい場合などの要件もあるため、
WebAPI を、完全に、この REST 基準に準拠させなくてもイイ気がする。

このようなケースには、JSON-RPC が適合するかもしれない。

リソースを決定する

  • リソース: 記事, コメント, タグ, カテゴリなど。
  • 操作: Create（生成）／ Read（読み取り）／ Update（更新）／ Delete（削除）
  • 親子関係: リソース間の包含関係を URI に反映する。

URIを決める

ディレクトリ or サブドメイン

２つの方法がある。

  • https://{FQDN名}/api
  • https://api.{ドメイン名}/

バージョン

  • 以下は、URI のバージョンを採用した場合の例。
  • 他にも、ヘッダや、クエリ文字列による方法がある。

リソースの関係性

リソース名は複数形の名詞のみで構成し、ID を指定して特定する。

https://api.{ドメイン名}/{version}/{複数形のリソース名}/{id}

親子関係がある場合、以下のように関係性を表す。

https://api.{ドメイン名}/{version}/{parent_resources}/{id1}/{child_resources}/{id2}

動詞ではなく名詞を使う

操作は HTTP メソッドで決める。

ページング

  • 大きな結果セットを返す場合、ページングを行なう。
  • クエリ文字列を使用して、ページ番号を指定する。

補足: 件数の多いデータでは ?page=100 形式（オフセット ページング）は DB 側で毎回スキャンが発生して深いページほど遅くなり、 かつページ跨ぎで重複・欠落が起きる。 カーソル（キーセット）ページング （?after=<最後の要素のキー>）のほうが安定する。

その他

  • 拡張子は含めない。
  • URL を短くする。

HTTPメソッドを決定する

POST, GET, PUT, DELETE を使用する。

メソッド 用途 備考
POST 生成 PUT と違い、ID が自明でない場合に使用する（自動採番）
GET 読み取り リソースを取得する
PUT 更新 存在しなければ新規作成、存在すれば置き換え。ID が自明な場合に使用する
DELETE 削除 リソースを削除する

その他

  • 自動採番がある POST 以外、何度同じ操作をしても処理結果は普遍（冪等）。

  • クライアントが PUT と DELETE をサポートしていない場合、
    パラメータに ?_method=PUT などと付与する。

補足: 部分更新には PATCH（RFC 5789）を使う。 PUT は「置き換え」なので、送らなかった項目が消える点に注意すること。

また「冪等（idempotent）」と「安全（safe）」は別概念である。 GET は安全かつ冪等、PUT / DELETE は安全でないが冪等、 POST はどちらでもない。 ネットワーク断でのリトライ可否は冪等性で決まるため、 POST をリトライさせたい場合は Idempotency-Key ヘッダのような仕組みを別途用意する。

リターンを決める

HTTPステータスコード

個別

  • GET — 成功: 200 OK / 304 Not Modified
  • POST — 成功: 201 Created（Location ヘッダ）／ 303 See Other（Location ヘッダ）／ 失敗: 409 Conflict（重複）
  • PUT — 成功: 201 Created（新規・Location ヘッダ）／ 204 No Content（更新）／ 失敗: 409 Conflict（ロック中）
  • DELETE — 成功: 204 No Content ／ 失敗: 409 Conflict（ロック中）

共通

  • 4xx: 400 Bad Request, 401 Unauthorized, 402 Payment Required, 404 Not Found, 405 Method Not Allowed, 406 Not Acceptable, 415 Unsupported Media Type
  • 5xx: 500 Internal Server Error, 503 Service Unavailable

補足（正誤）: 401 Unauthorized は名前に反して「未認証」、 403 Forbidden が「認証済みだが権限が無い」である。 401 を返す場合は WWW-Authenticate ヘッダの付与が HTTP の仕様上必須である点も見落とされやすい。

また、レート制限には 429 Too Many Requests（RFC 6585）を使う。

HTTPヘッダ

  • Location ヘッダでリソースの URI を示す。

一貫性のあるエラーペイロード

{
    "messageID": "xxxxx",
    "message": "yyyy yyyy yyyy."
}

補足（最新化）: エラー ペイロードの形式には RFC 9457 Problem Details for HTTP APIs（旧 RFC 7807）という標準がある。 ASP.NET Core は ProblemDetails として標準サポートしている。

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30.",
  "instance": "/account/12345/msgs/abc"
}

バージョン

バージョン情報が省略されている場合、既定値を使用する。

方式 例
URI のバージョン https://api.{ドメイン名}/{version}/...
クエリ文字列のバージョン https://api.{ドメイン名}/...?version={version}
ヘッダーのバージョン Custom-Header: api-version={version}
MIME タイプのバージョン Accept: application/vnd.....v1+json

参考

Tags: .NET開発, 通信技術, .NET Standard, .NET Core, ASP.NET, ASP.NET Web API

このWikiは「Open棟梁Project」,「OSSコンソーシアム 開発基盤部会」によって運営されています。

NetDevInfraWiki

マイクロソフト系技術情報 Wiki
Open 棟梁 Wiki

（未着手）

開発基盤部会 Wiki

移行管理: DONE ／ TODO

Clone this wiki locally