[[Open棟梁Project>http://opentouryo.osscons.jp/]] - [[マイクロソフト系技術情報 Wiki>http://techinfoofmicrosofttech.osscons.jp/]] -[[戻る>.NET開発]] * 目次 [#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]]