REST API設計について学ぶ①

Posted at 2021-04-25

要件定義、設計のフェーズでAPIの設計がとても大事であると痛感しています。
きちんと学びたいと思い勉強中です。

間違い等あればご指摘いただけましたら幸いです。

REST APIとは

私がプログラミングを学んでいて最初に認識したAPIというのは、例えばTwitterやAmazonなどそのサービスを外部から使うというようなものでした。
自身の作ったアプリにGoogleの検索バーを入れるとかそういうものだと思っていました。

で、実際に就職して初めて先輩と一緒にやった仕事がAPI連携設計で「ん？APIって私が思っているものと違うのかな」と混乱しました。

認識を確認するために読んだ記事が以下です。

厳格な定義はないが、広義にはHTTPプロトコルを用いてネットワーク越しに呼び出すアプリケーション間、システム間のインターフェースのこと。

とあります。なるほど。
つまり「呼び出す側」と「呼ばれた側」がいてそこを繋ぐインターフェースはWebAPIというんだと分かりました。
APIのIはインターフェースですからね。接続とかやりとりするポイントっていう意味で考えれば納得できます。

なのでREST API設計では、HTTPメソッドはどれか、URIはどうするか、必要なパラメータは何か、どんなレスポンスが返ってくるかを考えることなのだと認識しました。

めちゃくちゃ簡単なCRUDの例で考えます。
ショッピングサイトで考えてみましょう。

上記の書籍では
①各リソースの関係を考える
②アクション、パラメータ、レスポンスを考える
③リソースのパス(URI)を考える
④HTTPプロトコルで表す
というステップを紹介していました。

誰が、何を、どのようにする機能なのかを洗い出し、その機能のゴール=REST APIに置き換えるといいとのことでしたので、そうすると、下記のように考えればいいのでしょうか。

このどのようにの部分がAPIのゴールと考えます。
これを実現するにはどのようにしたらいいかを考えていきます。

アクションもどのようにで考えた部分ですね。
取得、更新、追加、削除の3つが出てきました。

パラメータは何を渡したら期待通りの出力がされるかを考えればいいのかなと思っています。
例えば、商品の詳細を取得したければその商品のIDが必要とか。
こちらは以前記事にまとめています。
リクエストパラメータについて

レスポンスは、何が返ってくればどのようにの要件が満たされるのかを考えればいいのかなと思っています。
例えば、商品の一覧を表示するゴールであればそのデータですね。

こちらはエンドポイントを考えることとほぼイコールであると考えています。
これはいろんな考え方があるので正解！っていうのはないみたいですが、一般的にこうするべきというのは様々な記事で紹介されていました。
私が参考にしたのは以下の記事です。
RESTful APIのURI設計(エンドポイント設計)

ということで、今回の例でいうと

商品の一覧取得と商品の登録は/productsとしてみます。
商品の詳細取得と編集と削除はその商品を特定するべきなので/products/{productID}とします。

こちらはつまりGET、POST、PUT、PATCH、DELETEのHTTPメソッドで表すということです。

一覧取得と詳細取得は取得なのでGETですね。
商品の登録は情報を送るのでPOSTですね。
削除はDELETE。
更新は場合によるのですが今回はPATCHにしておきます。

ということで今回考えた設計でいうと以下のようになります。
レスポンスやパラメータは場合によって変わると思うのですが分かりやすく？しています。

ゴール(機能の要件)	パラメータ	レスポンス	URI
商品の一覧を取得する		商品の一覧	/products
商品の詳細を取得する	商品のID	商品の詳細情報	/products/{productID}
商品を追加、登録する	商品の登録情報	登録した情報	/products
商品を編集、更新する	商品の編集情報、商品のID	更新した情報	/products/{productID}
商品を削除する	商品のID		/products/{productID}

このようにたくさんのAPIが繋がりあってサービスってできていくんですね。
確かにこれを間違えると開発大変そうです。

今回はここまでにします。