- 追加された行はこの色です。
- 削除された行はこの色です。
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicrosofttech.osscons.jp/]]」は、「[[Open棟梁Project>https://github.com/OpenTouryoProject/]]」,「[[OSSコンソーシアム .NET開発基盤部会>https://www.osscons.jp/dotNetDevelopmentInfrastructure/]]」によって運営されています。
-戻る
--[[RPC]]
--[[WebAPI]]
* 目次 [#g59f85eb]
#contents
*概要 [#i8b159d9]
JSONを返すWebAPIを、ざっくりREST APIとか~
言っているケースが多いので、定義を明らかにする。
**広義 [#b10a75e0]
2000年にRoy Fielding氏が提唱した、分散システムにおいて~
複数のソフトウェアを連携させるのに適した設計原則の集合。
**狭義 [#n3345889]
[[上記>#b10a75e0]]の設計原則をWebに適用したソフトウェアの設計様式~
（一般的には、コチラの狭義の意味が用いられている）
***一般によく使われる狭義のREST [#a248790d]
-パラメータを指定して特定のURLにHTTPでアクセスすると、~
JSON（、XML）で記述されたメッセージが送られてくるような~
WebAPI（「RESTful API」と呼ばれる）のことを指す。
-厳密な技術的定義が共有されているわけではなく、~
「SOAPやRPCなどを必要としない、JSON（、XML）を返すWebAPI」~
くらいの意味で用いられる場合が多い。
***RESTの設計原則（抽象的な概念） [#b1ec342e]
Fielding氏が示したRESTの設計原則（抽象的な概念）。
-セッションなどの状態管理を行わない。~
やり取りされる情報はそれ自体で完結して解釈することができる。
-情報を操作する命令の体系が予め定義・共有されている。~
HTTPのGETやPOSTなどに相当
-すべての情報は汎用的な構文で一意に識別される。~
HTTPのURLやURIに相当
-内部に、別の情報や、その情報の別状態へのリンクを含めることができる。~
HTMLやJSON、XMLに相当
理論上はHTTPやXMLとはまったく無縁なRESTシステムもあり得る。
*設計ポイント [#s787f45a]
RESTは疎結合で、不特定多数の開発者を相手にする場合は優れた方法らしい。
コレを実現するRESTの設計のポイントだが、ざっくり、~
以下手順により、指定のURIで指定のリソースに対する操作を実現する。
-リソースを決定する。
-URIを決める。
-HTTPメソッドを決定する。
-リターンを決める。
・・・翌々見てみると、RESTはデータ中心が過ぎるので、~
機能中心のURIにしたい場合などの要件もあるため、~
WebAPIを、完全に、このREST基準に準拠させなくてもイイ気がする。
このようなケースには、[[JSON-RPC>RPC#g8bee649]]が適合するかもしれない。
**リソースを決定する。 [#ae463dca]
***リソース [#r09c258f]
記事, コメント, タグ, カテゴリなど。
***操作 [#o1518765]
-Create（生成）
-Read（読み取り）
-Update（更新）
-Delete（削除）
***親子関係 [#x86f2933]
**URIを決める。 [#babd1da4]
***ディレクトリ or サブドメイン [#ka0ea5ed]
２つの方法がある。
-http://{FQDN名}/api
-http://api.{ドメイン名}/
***バージョン [#jf4c6435]
http://api.{ドメイン名}/{version}/
***リソースの関係性 [#yc0461e3]
リソース名は複数形の名詞のみで構成し、IDを指定して特定する。
-http://api.{ドメイン名}/{version}/{複数形のリソース名}/{id}
親子関係がある場合、以下のように関係性を表す。
-http://api.{ドメイン名}/{version}/{parent_resources}/{id1}/{child_resources}/{id2}
***動詞ではなく名詞を使う [#rbac1ad2]
[[操作はHTTPメソッドで決める。>#gbcd62e8]]
***ページング [#baa3c3f8]
-大きな結果セットを返す場合、ページングを行なう。
-QueryStringを使用して、ページ番号を指定する。
***その他 [#g2d7deda]
-拡張子は含めない。
-URLを短くする。
**HTTPメソッドを決定する。 [#gbcd62e8]
POST, GET, PUT, DELETEを使用する。
***POST（生成） [#z98f8fdc]
-リソースを新規作成する。
-PUTと違い、IDが自明でない場合に使用する（自動採番）。
***GET（読み取り） [#a799e397]
リソースを取得する。
***PUT（更新） [#h9b7d02a]
-リソースが
--存在しない場合~
リソースを新規作成する。
--存在する場合~
リソースを更新(置き換え)する。
-POSTと違い、IDが自明な場合に使用する。
***DELETE（削除） [#c128cb10]
リソースを削除をする。
***その他 [#t7396feb]
-自動採番があるPOST以外、何度同じ操作をしても処理結果は普遍（冪等）。
-クライアントがPUTとDELETEをサポートしていない場合~
パラメータに「?_method=PUT」などと付与する。
**リターンを決める。 [#r7609eea]
***HTTPステータスコード [#mf0b032f]
個別
-GET
--成功
---200 OK
---304 Not Modified
-POST
--成功
---201 Created（[[Locationヘッダ>#da178b40]]）
---303 See Other（[[Locationヘッダ>#da178b40]]）
--失敗
---409 Conflict（重複）
-PUT
--成功
---201 Created（新規）（[[Locationヘッダ>#da178b40]]）
---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
***HTTPヘッダ [#da178b40]
-LocationヘッダでリソースのURIを示す。
***一貫性のあるエラーペイロード [#v4baec73]
{
"messageID": "xxxxx",
"message": "yyyy yyyy yyyy.",
}
*参考 [#z9bf8448]
-RESTとは｜REpresentational State Transfer － 意味 / 定義 / 解説 / 説明 ： IT用語辞典~
http://e-words.jp/w/REST.html
-REST APIとは？ - API設計のポイント~
http://wp.tech-style.info/archives/683
-RESTのベストプラクティス | 開発手法・プロジェクト管理 | POSTD~
http://postd.cc/some-rest-best-practice/
-RESTful API設計におけるHTTPステータスコードの指針 - Qiita~
http://qiita.com/uenosy/items/ba9dbc70781bddc4a491
----
Tags: [[:プログラミング]], [[:通信技術]], [[:.NET開発]], [[:.NET Core]], [[:ASP.NET]], [[:ASP.NET Web API]]
Tags: [[:プログラミング]], [[:通信技術]], [[:.NET開発]], [[:.NET Core]], [[:.NET Standard]], [[:ASP.NET]], [[:ASP.NET Web API]]
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
