これからシステムにAPIを組み込んでいこうとした場合、まず真っ先に思いつくのがRESTful APIではないでしょうか。なんとなくは分かっているつもりでも、意外といざ実装してみると難しいのがRESTful APIです。今回はその基本的な考えを紹介します。
HTTP/HTTPSアクセス
RESTful APIではHTTPまたはHTTPSアクセスが基本になります。ネットワークのプロトコルは他にもたくさんありますが、RESTfulな実装に向くのはHTTP/HTTPSになるでしょう。
HTTPメソッドがアクションを表す
GETは取得、POSTは作成、PUT/PATCHは更新、DELETEは削除を表します。
パスがリソースを表す
例えば GET /users/1 であればユーザID=1に対する操作を意味します。 GET /users/1/posts であればユーザID=1の持っているポスト一覧を意味します。POST /users/1/posts であれば、ユーザID=1の新規投稿を意味すると言った具合です。
パスとHTTPメソッドを見れば、どのリソースに対して何の処理を行うかが分かるようになっています。usersはサービスやモデルの単位で設定し、その後の1という数字はサービス中のユニークなIDを示します。
クエリーで細かな条件を指定する
さらにURLのクエリーを使って操作内容の細かな指定を行います。例えば一覧画面の場合、取得件数を指定するのが一般的です。その際、 GET /users/1/posts/limit/100 とはしません。 GET /users/1/posts?limit=100 とします。
データリソースの一覧を取得するという処理は決まっていますので、その詳細についてはクエリーやbodyを使って表現します。
取得するデータフォーマットを指定する
RESTful APIではJSONまたはXMLでデータの送受信を行うことが多いです。その際、フォーマットの指定方法は主に2パターン考えられます。一つはパスに含める方法で、 GET /users/1.json といった具合です。もう一つはクエリで指定する方法で、 GET /users/1?format=json のように行います。
RESTfulの原則に則って開発するのはシステムの可読性を維持し、さらにメンテナンス性も良くします。パスの切り方などもRESTfulの原則に則っていれば、何の処理を行うのかも一目で分かるようになります。
簡単なルールしかないために、ついつい拡張したり、オリジナルルールを混ぜ込んだりしてしまいがちです。しかし、それをぐっと堪えて書くことで見通しの良いシステムを維持できるでしょう。
