「マイクロソフト系技術情報 Wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。
目次 †
概要 †
JSONを返すWebAPIを、ざっくりREST APIとか
言っているケースが多いので、定義を明らかにする。
広義 †
2000年にRoy Fielding氏が提唱した、分散システムにおいて
複数のソフトウェアを連携させるのに適した設計原則の集合。
狭義 †
上記の設計原則をWebに適用したソフトウェアの設計様式
（一般的には、コチラの狭義の意味が用いられている）
一般によく使われる狭義のREST †
- パラメータを指定して特定のURLにHTTPでアクセスすると、
JSON（、XML）で記述されたメッセージが送られてくるような
WebAPI（「RESTful API」と呼ばれる）のことを指す。
- 厳密な技術的定義が共有されているわけではなく、
「SOAPやRPCなどを必要としない、JSON（、XML）を返すWebAPI」
くらいの意味で用いられる場合が多い。
RESTの設計原則（抽象的な概念） †
Fielding氏が示したRESTの設計原則（抽象的な概念）。
- セッションなどの状態管理を行わない。
やり取りされる情報はそれ自体で完結して解釈することができる。
- 情報を操作する命令の体系が予め定義・共有されている。
HTTPのGETやPOSTなどに相当
- すべての情報は汎用的な構文で一意に識別される。
HTTPのURLやURIに相当
- 内部に、別の情報や、その情報の別状態へのリンクを含めることができる。
HTMLやJSON、XMLに相当
理論上はHTTPやXMLとはまったく無縁なRESTシステムもあり得る。
設計ポイント †
RESTは疎結合で、不特定多数の開発者を相手にする場合は優れた方法らしい。
コレを実現するRESTの設計のポイントだが、ざっくり、
以下手順により、指定のURIで指定のリソースに対する操作を実現する。
・・・翌々見てみると、RESTはデータ中心が過ぎるので、
機能中心のURIにしたい場合などの要件もあるため、
WebAPIを、完全に、このREST基準に準拠させなくてもイイ気がする。
このようなケースには、JSON-RPCが適合するかもしれない。
リソースを決定する。 †
リソース †
記事, コメント, タグ, カテゴリなど。
操作 †
- Create（生成）
- Read（読み取り）
- Update（更新）
- Delete（削除）
親子関係 †
URIを決める。 †
ディレクトリ or サブドメイン †
２つの方法がある。
バージョン †
- 以下は、URIのバーションを採用した場合の例
- 他にも、ヘッダや、クエリ文字列による方法がある。
リソースの関係性 †
リソース名は複数形の名詞のみで構成し、IDを指定して特定する。
親子関係がある場合、以下のように関係性を表す。
- http://api.{ドメイン名}/{version}/{parent_resources}/{id1}/{child_resources}/{id2}
動詞ではなく名詞を使う †
操作はHTTPメソッドで決める。
ページング †
- 大きな結果セットを返す場合、ページングを行なう。
- クエリ文字列を使用して、ページ番号を指定する。
その他 †
HTTPメソッドを決定する。 †
POST, GET, PUT, DELETEを使用する。
POST（生成） †
- リソースを新規作成する。
- PUTと違い、IDが自明でない場合に使用する（自動採番）。
GET（読み取り） †
リソースを取得する。
PUT（更新） †
- 存在しない場合
リソースを新規作成する。
- 存在する場合
リソースを更新(置き換え)する。
DELETE（削除） †
リソースを削除をする。
その他 †
- 自動採番があるPOST以外、何度同じ操作をしても処理結果は普遍（冪等）。
- クライアントがPUTとDELETEをサポートしていない場合
パラメータに「?_method=PUT」などと付与する。
リターンを決める。 †
HTTPステータスコード †
個別
共通
- 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
HTTPヘッダ †
一貫性のあるエラーペイロード †
{
"messageID": "xxxxx",
"message": "yyyy yyyy yyyy.",
}
バージョン †
バージョン情報が省略されている場合、既定値を使用
URIのバーション †
http://api.{ドメイン名}/{version}/.../
クエリ文字列のバージョン †
http://api.{ドメイン名}/.../?version={version}
ヘッダーのバージョン †
GET https://... HTTP/1.1
Custom-Header: api-version={version}
MIMEタイプのバージョン †
前述のAPIのバージョンに加え、
MIMEタイプのバージョンを指定。
GET https://....com/.../{version} HTTP/1.1
Accept: application/vnd.....v1+json
参考 †
Tags: :.NET開発, :通信技術, :.NET Standard, :.NET Core, :ASP.NET, :ASP.NET Web API
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
