REST APIを設計する方法（2018年版設計指針 Json to Json方式）
2018/12/15
REST API（クラウドAPI）を設計する方法（設計指針）
いわゆるREST APIとは、SOAP APIと区別するために、そう呼ぶだけであり、現在はSOAP APIは使われていないため、単にWeb APIやクラウドAPIと言っても差し支えない。
ただ、文脈が確定しないところで、APIと呼ぶのは避けたい。
APIには、その名前の通り、アプリと何かのインタフェース（結束点）となる、次のようなものが含まれているからだ。
・OS API
・Framework API
・ライブラリ API
・クラウドサービス API
REST APIとは、HTTPプロトコルを使って、クラウドとエンドノードが通信する仕組みのことである。
REST APIは２０年も前に提唱されたもので、その実装方法は日々進化している。
ブラウザがその代表で、世界中のコンピュータとREST APIで通信している。
誤解を恐れずに言えば、「インターネット通信＝REST API」なのである。
ただし、ここで述べるREST APIは少し異なる。
ブラウザに打ち込むいわゆる「URL、アドレス」ではなく、プログラマだけが用いるエンドポイントとしてのREST APIについて述べている。
ブラウザでアクセスするURL、ウェブサイトはGoogleのSEO方針に従わないと、Googleの検索結果に都合よく表示してくれない可能性が高いからだ。
REST APIを設計する際に、多くのプログラマが、ウェブ検索し、古くなってしまった情報やら未熟なプログラマが公開した情報を鵜呑みにして、まるでそれらがREST APIのRFC仕様や制限であるかのように思い込んでしまっているのである。
例えば次のようなものだ。
js
＜REST API 誤った思い込み＞
・REST APIもGoogle SEOの方針に従い設計することが望ましい。
・REST APIはプロトコル（通信規約）であり、絶対に守らなければならない。（取得はGETメソッド、削除はDELETEメソッドなど）
・パス名は英小文字とハイフンでなければならない。
・クエリパラメータ名も英小文字とハイフンでなければならない。
・大文字と小文字が混在したAPIは誤動作の可能性が高い。
・クエリパラメータはGETメソッドでURLにする、もしくは POSTメソッドのapplication/x-www-form-urlencoded にした方がプログラムで扱いやすい。
前提としてエンドポイントAPIとしてのREST APIはプログラマだけが目にするものであって、アプリ利用者は目にすることはない。
利用者が目にするサイトのURLとは根本的に設計思想が異なるのである。
ウェブサイトAPI : Googleに好かれるURL、ユーザが入力しやすさ
エンドポイントAPI : 効率的にプログラムできる、プログラマの間違いが少ない
以上のことから、REST APIは、プログラムがリファレンスをいちいち参照しなくとも利用しやすい（プログラムしやすい）ということだけを考えれば良いことになる。
最初に議論したいのは、命名規則についてだ。
ほんとに全て小文字で設計するべきなのだろうか？
例えば上記の思い込みで設計するとAPIは次のような命名となる。
https://cloud-fqdn/rest-api-path/request-parameter
なるほど、単語の区切りはわかりやすいと言えば分かりやすいが、VisualStudioCodeなど多くの開発環境でハイフンは単語区切りとみなされるため、パスやパラメータをダブルクリックで簡単に選択することができない。
会話する場合にも、request-parameterは「リクエスト ハイフン パラメータ」と呼ぶことになり、煩わしい。
クライアント言語であるJS ES6などほとんどの言語でclass名やプロパティ名に「ハイフン」を用いることはないため、REST APIのリクエストを生成する際や、レスポンスで受け取ったデータを変数に代入する際にも脳内変換を強いられることになる。
request-parameter APIリクエストパラメータ
↓
requestParameter プロパティ
「英大文字を使うとAPIが誤動作を起こす」というデマゴーグは、パソコン用OSでは歴史的な理由からファイルシステムにおいて、英小文字と大文字を区別しないことに由来している。
実際、Windows10やmacOSのファイルシステムは、デフォルトで英小文字と大文字を区別しないが、クラウドでこれらのOSを用いることはない。
仮に用いたとしても、問題が発生することは考えられない。
また、REST APIパスの命名規則について、私は大文字始まり（パスカルケース）を推奨する。
先ほどの例で命名すると次のようになる。
https://cloudFqdn/RestApiPath/requestParameter
REST APIのパスはプログラムのclass にあたるものであるので、JS ES6など多くのプログラム言語の命名規則に従い、パスカルケースで命名すると、一目でそれがAPIパスであることをアプリプログラマが判断できるようになる。
リクエストパラメータについてもプログラム言語のプロパティと同様にローワキャメルケースで命名すると、jsonプロパティでもそのままの名称で使用できるため、アプリプログラマはプログラムしやすい。
最後に議論したいのが、POST Bodyのエンコード方法である。
・application/x-www-form-urlencoded
古くからHTML formタグで用いられてきた application/x-www-form-urlencoded（クエリパラメータ形式）だが、配列型データや連想配列型データを扱う場合に注意が必要な場面がたびたび出てくる。
・application/json
最近では、application/x-www-form-urlencodedではなく、application/json（jsonテキスト）が用いられている。
配列や連想配列など柔軟なデータ型が扱えるからだ。
それに伴い、バイナリ（ファイル、画像など）を扱う場合は、Base64にエンコードした上で、jsonプロパティのString値として指定するようになっている。
js
＜まとめ＞
・REST APIパス名はパスカルケース(PathName)とする。
・リクエストパラメータ名はローワキャメルケース(requestParameter)とする。
・HTTP ContentTypeはapplication/jsonとし、jsonでリクエストして、jsonでレスポンスを受け取る Json to Json 方式とする。