- 追加された行はこの色です。
- 削除された行はこの色です。
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicrosofttech.osscons.jp/]]」は、「[[Open棟梁Project>https://github.com/OpenTouryoProject/]]」,「[[OSSコンソーシアム .NET開発基盤部会>https://www.osscons.jp/dotNetDevelopmentInfrastructure/]]」によって運営されています。
-[[戻る>RPC]]
-戻る
--[[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]
2つの方法がある。
-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]]