進捗は勝手に降ってこない

書きたいことを書きます

久々の更新。RESTfulつらいって話の続き。

久しぶりの更新です。 

今年の4月から働き始めたこともあって、この時期になりました。

 

更新しない間にあったことと言えば、

普段使ってるSNSのMisskeyにカスタムテーマの昨日が実装されて喜んでたり、

Misskeyでわいわいお話をしたり、

Frost-APIの設計を考えたり、

久々にMinecraft(Java版)をプレイしたり、

そんな感じでした。平和というか平凡というか。

 

さて、以前の更新で書いたRESTfulなAPIがつらいって話の続きを書きたいと思います。

RESTがシンプルで美しいのはそうなんですが、いくつかつらい部分もあり、最近はRESTに変わるようなHTTP APIのエンドポイント設計を試行錯誤しています。

 

今考えてるのは次のようなスタイルです。

1. 基本的にエンドポイントは全てPOSTメソッド固定

2. URLパスの一番最後の部分を動詞にする(例: /user/relation/get)

 

このスタイルにはいくつかのメリットがあります。

その1つ目は、全てのエンドポイントでリクエストbodyを使えるという点です。

GETメソッドはbodyにパラメータを付加することができないため、JSONなどの構造化されたデータをパラメータとして渡すには適していません。無理やりする場合は、クエリ文字列としてJSONを渡したり、クエリ文字列に何らかの工夫をする必要が出てきます。

常にPOSTを使うことによって全てのエンドポイントでbodyを使うことが出来るため、上記の問題を解消できます。

 

2つ目のメリットは、リソースに対する操作を自由に命名できるという点です。

HTTPのメソッドで操作を表そうとすると、HTTPメソッドのGET、POST、PUT、PATCH、DELETE等で全ての操作を表す必要があり、少し表現力が乏しいと感じます。

実際、RESTfulなAPIを作っていたりすると、検索をするエンドポイントのHTTPメソッドは何を使おう...ユーザーをフォローするときのHTTPメソッドは何を使おう...というような感じで、やりたいこととは直接関係ない部分で考え込むことがよくあります。

何らかの単一のデータを取得する操作には「get」、

コレクションのデータを取得する操作には「list」、

データの作成には「create」、更新には「update」、削除には「remove」(もしくはdelete)。

この5つを基本として、必要であれば「follow」「unfollow」「validate」「search」「check」「filter」など..自由に用意できるので、リソースへの操作を自由に表現することができ、その操作の意味も伝わりやすくなることが期待できます。

 

これについては賛否あると思いますが、HTTPのつらさを補う1つの方法として参考にしてみてはどうでしょうか。

 

GitHubのissuesで試行錯誤の様子を見れます:

エンドポイントの形式をリニューアルしたい · Issue #118 · Frost-Dev/Frost-API · GitHub

 

過去にTwitterでやったアンケート:

 

(c) 2017- まりはち