マイクロソフト系技術情報 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で指定のリソースに対する操作を実現する。

  • リソースを決定する。
  • URIを決める。
  • HTTPメソッドを決定する。
  • リターンを決める。

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

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

リソースを決定する。

リソース

記事, コメント, タグ, カテゴリなど。

操作

  • Create(生成)
  • Read(読み取り)
  • Update(更新)
  • Delete(削除)

親子関係

URIを決める。

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

2つの方法がある。

バージョン

http://api.{ドメイン名}/{version}/

リソースの関係性

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

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

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

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

動詞ではなく名詞を使う

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

ページング

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

その他

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

HTTPメソッドを決定する。

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

POST(生成)

  • リソースを新規作成する。
  • PUTと違い、IDが自明でない場合に使用する(自動採番)。

GET(読み取り)

リソースを取得する。

PUT(更新)

  • リソースが
  • 存在しない場合
    リソースを新規作成する。
  • 存在する場合
    リソースを更新(置き換え)する。
  • POSTと違い、IDが自明な場合に使用する。

DELETE(削除)

リソースを削除をする。

その他

  • 自動採番があるPOST以外、何度同じ操作をしても処理結果は普遍(冪等)。
  • クライアントがPUTとDELETEをサポートしていない場合
    パラメータに「?_method=PUT」などと付与する。

リターンを決める。

HTTPステータスコード

個別

  • GET
    • 成功
      • 200 OK
      • 304 Not Modified
  • PUT
    • 成功
    • 失敗
      • 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ヘッダ

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

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

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

参考


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


トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2018-03-07 (水) 11:33:12 (468d)