OpenAPIにはREST APIよりもRPCのほうが適していると思う件
現在、新規プロジェクトで通信仕様をメンバーと話して決めている最中です。
その中で出た話も交えつつ掲題の話をしていこうと思います。
まずスキーマファーストでいきたい
通信定義を書くと、フロントとバックエンドで通信するコードが生成される状態としたい。
昔は、通信定義をExcelで書いていた時期もありました。
ですが、今ではスキーマ定義して生成してGitで管理もできる良い時代になりました。
- OpenAPI
- gRPC
- GraphQL
- Apache Thrift
スキーマファーストで使う有名どころの通信プロトコルは上記かと思いますが、httpで特殊なことしなくても通信できるものが良いという話が出て、OpenAPI に決定しました。
OpenAPIでREST API or RPC?
OpenAPIはHTTPの通信仕様を定義するものなので、RESTスタイルで行くか？RPCスタイルで行くか？は選べます。
どちらにするか？の前に「個人的に思う良いルールの定義」について話したいです。
個人的に思う良いルールの定義
個人的には、良いルールというのは人によって解釈がブレないものだと思います。
例を挙げると、「好きな飲み物を飲む」というルールだと人によって飲むものが違いますが、「スタバラテを飲む」というルールだと人によって異なることはない。といった感じです。
REST APIだとブレると思う
静的な名称をURLにつけるという仕様のせいか、銀行間送金など動的な処理に対して、命名がしづらかったりします。
また、URLにパラメータが含まれたりしますが、どこに含むのか？とかも結構違ったりして、ブレるなぁという印象があります。
（見てきた現場では、/hoge/${param}/fuga みたいなものもありました）
（上記のURLだと、コード内をURLで検索したときにヒットが多くなり探しづらいというのもあります）
そこでRPCです
RPCだと命名に動的な名前を付けるので、ドメイン駆動設計を取り入れる場合でも素直に命名できると思います。
銀行間送金なども、動作なのでそのまま命名できます。
パラメータもURLに含まないのでブレることはありません。
コードをGrepしたときに見つけやすいし、とてもシンプルで良いです。
個人的にシンプルさは銀の弾丸になりえると思っています。
なんとあのDropboxもV1からV2でRESTからRPCに変更しました
Dropboxそんなに有名か？とか言わない。
/list_folder
/list_folder/continue
/list_folder/get_latest_cursor
/list_folder/longpoll
ちょっと抜粋するとこんな感じです。
API仕様なので使うエンジニアが分かりやすいことを重視してRPCに変えたのでは？と思いますが、一般ユーザ向けシステムでも分かりやすくて良いと思われます。
DropboxのAPI変更の話は仕事仲間から情報提供で知りました。感謝です！！
HTTPのGETとPOSTについて
全部POSTにするという意見もあるみたいですが、僕はGraphQLのように参照系はGET。更新系はPOSTとするのが良いと思います。
参照系はブラウザにURL打ち込むだけで結果を確認できるので、その開発フィールは良いものだと思います。
更新系は情報量などの話もあるので、POSTで良いと思いますしGETとPOSTで分かれていた方が見やすいです。
そしてイレギュラーではありますが利便性を考慮して、ログアウトだけは例外でGETで動作するようになっているとログアウト案内とかもリンクでできてよかった経験があります。
さいごに
RESTが悪いとは言わないですが、脳死で決めずに色々と考えて現場にあった方法を採用してほしいと思いました。
Discussion