RESTful API

定義

REpresentational State Transfer

たぶん、説明的な状態のやり取りをするアプリケーションインターフェイス

5.16. RESTful Web Service — TERASOLUNA Global Framework Development Guideline 1.0.1.RELEASE documentation
https://terasolunaorg.github.io/guideline/1.0.1.RELEASE/ja/ArchitectureInDetail/REST.html

クライアントとサーバ間でデータをやりとりするアプリケーションを構築するためのアーキテクチャスタイルの一つ

RESTful APIとは何なのか - Qiita
http://qiita.com/NagaokaKenichi/items/0647c30ef596cedf4bf2

REpresentational State Transferの略で、分散型システムにおける複数のソフトウェアを連携させるのに適した設計原則の集合、考え方のこと。Roy Fieldingが2000年に提唱した。

ほかにも、ここに書いていることを落ち着いて読むと、そもそものことがわかる気がする。
メリットが何かを整理しつつ、メリットを生かせる形で例外を作りたくなるような事例に対応していけばいいのかもな。

REST APIで世界中のAPPsとつながるクラウドERP ツバイソ｜つながるクラウドERP ツバイソ
https://tsubaiso.jp/about_tsubaiso/rest-api.html

REST APIは、2000年にRoy Fielding氏が提唱した、分散システムにおいて複数のソフトウェアを連携させるのに適した設計原則またはアーキテクチャスタイルをいいます。システム連携のために様々なAPIが古くからありますが、大規模なWEBシステムの運営、連携に適したアーキテクチャスタイルのAPIがREST APIです。 REST APIはアーキテクチャスタイルですから、実際に実装されたAPIの使いやすさ、拡張性、柔軟性は開発会社の技術力によって異なります。我々は、REST APIは、適切な粒度のモジュール化技術、ノウハウが重要と考え、日々研究開発しています。確かな技術によって作られたREST APIは、クラウドアプリケーションを世界中、大規模につなげることができます。

説明文章としてとてもわかりやすい。
（ERPとは、Enterprise Resource Planning）

RESTとその周辺

いろいろな概念があって混同はしたらダメらしい。なるほど。

《REST思想》と《リソース指向》と《Webページ》を一緒にしてはいけない - Qiita
http://qiita.com/irxground/items/cd83786b10d81eecce77

Open APIのわかりにくさ

オープンAPIとOpen APIととWeb APIとREST APIの違い。 - 自分の仕事を憎むには人生は余りにも短い
http://garapon.hatenablog.com/entry/2016/10/25/_%E3%82%AA%E3%83%BC%E3%83%97%E3%83%B3API%E3%81%A8Open_API%E3%81%A8%E3%81%A8Web_API%E3%81%A8REST_API%E3%81%AE%E9%81%95%E3%81%84%E3%80%82

Swagger specifications が寄贈されOpen API Spesificationという名称に変更。Swagger specificationsは「Swagger」と呼称されていたのでOpen API Spesificationが「Open API」と呼称されてしまったりしている。
まじめんどい。

オープンAPI

オープンAPIとは「ある企業が提供するAPIのうちサードパーティーがアクセス可能なAPI」の事を指します。

想定範囲

以下のようなことが想定されやすいみたいな気がする

CRUD操作をHTTPメソッドを利用する
Web API
リソース指向（フォーマットはURIで指定できる、リソースごとにURIを設計する）
リソースに対する操作はHTTPメソッド(GET,POST,PUT,DELETE)を使用して表現する

RESTの原則

なるほど。

制約に従いながらもHTTPを自由にするRESTful――『JavaによるRESTfulシステム構築』：晴読雨読＠エンジニアライフ：エンジニアライフ
http://el.jibun.atmarkit.co.jp/bookshelf/2011/01/post-e0e0.html

RESTでは以下の原則を定義する。
* アドレス可能なリソース
* 制約された統一インターフェイス
* 表現指向
* ステートレスな通信
* アプリケーション状態エンジンとしてのハイパーメディア

他ではリソース指向と説明されたりもしている内容が表現指向として示されてるのかな。

ステートレスな通信は、サーバーサイドで状態を管理しないということでいいのかな。
この辺は、APIをどの程度クライアントサイドで呼び出してオーバーヘッドを許容するかというようなこと、
RESTで設計すると複雑とも思える検索のような処理をどうするかということに絡みそう。

RESTだと扱いづらいかもしれない場合

Web API（REST API）のURL設計｜ Developers.IO
http://dev.classmethod.jp/etc/web-api_rest-api_url-design/

「GET /articles/333444」の方は自分の記事のみを取得するAPIとします。そして、他人の記事を取得するAPIを以下のように別途用意

リソースだけではなく、そのリソースへのアクセス権限によってURIを変化させる事例。

私が遭遇した例では「印刷する」「通知する（クライアントからサーバーに）」といったものがありました。
...
POST /processes/777888/notify

RESTの考えから抜け出て（？）動詞をURIに使った事例。

いくつかのリソースをまとめて削除するAPIを考えます。

あるリソースそれ自体ではなく、あるリソースに関連づくリソースを一括で削除するときどうするか。ということかな。

REST APIに消耗したらJSON RPCを試そう - タオルケット体操
http://hachibeechan.hateblo.jp/entry/try-json-rpc-great-good

最適化が難しい
...
出来上がるものはHTTPに密結合

場合によってはRESTで考えるとコストのほうが大きいということで、JSON PRCを使った事例。

Web API設計指針を考えた | MMMブログ
http://blog.mmmcorp.co.jp/blog/2015/07/01/web_api_guideline/

1つの作業を完結するために複数回のアクセスを必要とするようなAPIの設計はChatty APIと呼ばれる。これはネットワークのトラフィックを増加させ、クライアントの処理の手間を増やす。

なるほど。

URIに動詞を含める話

REST APIとは？ - API設計のポイント
http://wp.tech-style.info/archives/683

特にAPIのURL設計で意識すべき点を挙げてみます。

ひと目でAPIと分かるようなURLにする
URLにAPIのバージョンを含める
URLに動詞を含めず、複数形の名詞のみで構成する
アプリケーションや言語に依存する拡張子は含めない
リソースの関係性がひと目で分かるようにする
長くしすぎない
ちなみに良いURLはCool URIと言われ、半永久的に変わらないと言われています。

Cool URIか。動詞を含まないのはこの考え方からなのかな。RESTの原則か。。

REST サービスの作成
http://docs.intersystems.com/latestj/csp/docbook/DocBook.UI.Page.cls?KEY=GREST_services

一般的に、REST は GET、POST、PUT、または DELETE 操作を使用しますが、任意の HTTP 操作を指定することができます。URL には必要に応じてパラメータを含めることができます。このパラメータは、REST URL の一部として指定され、指定のメソッドにパラメータとして渡されます。

これも原則的ではなく例外を許容する考え方の例だな。

RESTの代替は必要か
https://www.infoq.com/jp/news/2014/01/rest-alternatives

真のRESTfulな原則とRESTfulと言われているが実際はそうでない実装を区別

だいぶ昔の記事だけど、RESTfulと呼ばれるものには、深堀すれば区別がありそう（できそう）ってことかな。
観点として、下記みたいなことらしい。
非同期通信、オーバーヘッド、JSON-RPCライクな手法、転送の効率化などで有意義なバイナリプロトコル
ここでもJSON RPC出てきてるのか。

シンプルにつくれるものはRESTに当てはめてシンプルにするのが有意義で、
それをはみ出るものは別で考えるって感じなのかなって気がしてきた。

「WebAPI 設計のベストプラクティス」に対する所感 - Qiita
http://qiita.com/ryo88c/items/0a3c7861015861026e00

エンドポイントを定義する際には上記のような暗黙知を必要としない表記を心がけるべきで、そのような性質を自己記述性と言います。
...
/search のようなエンドポイントを作らざるをえないような場合、そもそもとしてそのエンドポイントで示したい事象がほかと比べて大き（複雑）すぎるか具体的すぎる可能性があります。そのような場合には複数のエンドポイントに分割するか、もっと抽象的な設計とすべきです。
...
横断的に検索したい複数のリソースを包含するリソースが思いつかないような場合は、それらのリソースを横断的に検索するというアプローチ自体に問題がある可能性を考えた方が良いかもしれません。

動詞をURIに含めるべきではない的なお話とか注意とかかな。
この辺はまだ議論があるってことかな。

動詞を使う場合についてしっくりこない

WEB APIベストプラクティス的な記事でその辺まで書いてる記事を眺める

Web API（REST API）のURL設計｜ Developers.IO
http://dev.classmethod.jp/etc/web-api_rest-api_url-design/

世の中の機能がすべてGET,POST,PUT,DELETEで表現できたらよかったのですが、これらだけだと苦しいこともあります。私が遭遇した例では「印刷する」「通知する（クライアントからサーバーに）」といったものがありました。
いくつかのリソースをまとめて削除するAPIを考えます。

印刷、一括削除

これから始めるエンタープライズ Web API 開発 | オブジェクトの広場
https://www.ogis-ri.co.jp/otc/hiroba/technical/WebAPI/part2.html

ここまでリソースが名詞であることを前提に説明をしてきましたが、下記のように動詞でなければ表現しにくいものも存在します。

計算
翻訳
変換処理

LINE API Reference
https://devdocs.line.me/ja/#leave

lineの退出のAPI

結局どうすればいいのか

まず

基本部分はREST APIにする。

動詞を扱いたくなるような場合にどう対処するか。。

JSON RPCライクな手法にするとか、明示的に切り分ける。
動詞を許可する例外を設ける
- GETかPOSTか、、GETだとURIが明示的になるけど安全性とか他にも気を使うことがありそう

どういうアプリなのかという観点でパターンだしして考えてもいいのかもな。。

セキュリティとGETパラメータ

GETだとサーバーにログが保存される、アプリによって扱い（POSTもあるだろうけど、キャッシュとか）が緩いかも。
心配はくらいでいいのかな。
上記を認識しつつ、認証機構を導入をしていれば大丈夫かしら。

rest api get セキュリティ認証 - Google 検索
https://www.google.co.jp/search?num=100&safe=off&espv=2&q=rest+api+get+%E3%82%BB%E3%82%AD%E3%83%A5%E3%83%AA%E3%83%86%E3%82%A3+%E8%AA%8D%E8%A8%BC&oq=rest+api+get+%E3%82%BB%E3%82%AD%E3%83%A5%E3%83%AA%E3%83%86%E3%82%A3+%E8%AA%8D%E8%A8%BC&gs_l=serp.3...19672.20869.0.21163.9.7.0.0.0.0.348.348.3-1.1.0....0...1.1j4.64.serp..9.0.0.4P5ngNRdhCs

REST APIの認証設定について – cybozu developer network
https://cybozudev.zendesk.com/hc/ja/articles/202531474-REST-API%E3%81%AE%E8%AA%8D%E8%A8%BC%E8%A8%AD%E5%AE%9A%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6

第6回　WebAPI，認証APIのセキュリティ：ここが危ない！Web2.0のセキュリティ｜gihyo.jp … 技術評論社
http://gihyo.jp/dev/serial/01/web20sec/0006

WP REST API の OAuth 認証の方法と何が起こっているのかとなぜそんなことをしているのか - Shinichi Nishikawa's
https://nskw-style.com/2016/wordpress/wp-api/oauth1.html

REST セキュリティに関するチートシート - OWASP
https://jpcertcc.github.io/OWASPdocuments/CheatSheets/RESTSecurity.html

REST APIのセキュリティを取り巻く課題 - コラム詳細 | バラクーダ
http://www.barracuda.co.jp/column/detail/466

長いパラメータのときにGETにするべきか

意味合いはGET/POST=Read/Createじゃなくなるけど、POSTにしてしまうでいいのかな。。

api get post 長い - Google 検索
https://www.google.co.jp/search?num=100&safe=off&espv=2&q=api+get+post+%E9%95%B7%E3%81%84&oq=api+get+post+%E9%95%B7%E3%81%84&gs_l=serp.3...6317.8637.0.9223.8.8.0.0.0.0.218.881.0j4j1.5.0....0...1.1j4.64.serp..4.2.290...0j0i7i30k1j0i30k1j0i5i30k1.kGd2GKULHZk

RESTful APIで長い検索クエリを扱う - yuw27b’s blog
http://yuw27b.hatenablog.com/entry/2016/12/02/234101

部分置換のPATCHメソッドというのがあるのか。。

AWSのAPI Gateway APIでもPatchは使えるな。。

PUT か POST か PATCH か？ - Qiita
http://qiita.com/suin/items/d17bdfc8dba086d36115

idempotentな操作であるGitHubのスターをつけるAPIはPUT /user/starred/:owner/:repoになっています。一方、ブランチをマージする操作はPOST /repos/:owner/:repo/mergesになっています。

ちなみに、DELETEも操作としてはidempotentですが、リソースが無くなっている場合、2回目のDELETE
は404になるのが普通のようです。http - Is REST DELETE really idempotent? - Stack Overflow

githubを例にして冪等性とurl設計。
githubがやってるならありだろう。

API Gateway API リクエストとレスポンスペイロードのマッピングテンプレートのリファレンス - Amazon API Gateway
http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html

使用される HTTP メソッドです。有効な値には、DELETE、GET、HEAD、OPTIONS、PATCH、POST および PUT があります。

リソースの一部更新におけるURL設計 - Qiita
http://qiita.com/necojackarc/items/fd53c96865d0ef7a02d8

URL設計の超基本
更新系メソッドPUTとPATCHの違い
リソースの属性をリソースと捉える設計
...
URL設計はリソース (URL) と操作 (メソッド)
属性の状態や集合もリソースと見なすことができる
POSTとPATCHは非冪等、PUTは冪等
PUTは全置き換え、PATCHは部分置き換え

とても勉強になる。

使われ方をイメージする
リソースの属性を子リソースと捉える
冪等性とURLの明確さを認識する

ほか

RESTのベストプラクティス | 開発手法・プロジェクト管理 | POSTD
http://postd.cc/some-rest-best-practice/

複数形か単数系か
GETとHEADの安全性
リソースの入れ子
ページング
エラーコード
バージョンを URL に含めるべきか
HATEOAS

GoogleのWebAPI設計とWebAPI設計のベストプラクティスを比較してみる - Qiita
http://qiita.com/howdy39/items/3b2b14ce73ec44c54f7b

ベストプラクティスに照らし合わせていてわかりやすい

WebAPI学習ソースまとめ - Qiita
http://qiita.com/y-some/items/7e05540d7563f7c1c101

よさげな学習リソース

所感

WEB APIの勉強との線引きが難しくなってきた
だいぶ理解が進んだってことかな

REST APIについてのお勉強1

定義