REST API とは？ POST や PUTの時に APIは何を返すように設計したらいいの？

みなさん、こんにちは。どんぶラッコです。

今日は REST API と その戻り値についてお話しします。

REST API とは?

グランくん

そもそも REST APIって何？

どんぶラッコ

REST という設計思想を適用したAPIのことだね。 RESTful API なんて言い方もするよ

グランくん

なるほど、じゃあRESTという考え方が前提にあるってわけだ

どんぶラッコ

REST とは Representational State Transfer の略語だね。以下の4原則があるよ

どんぶラッコ

例えば、本の一覧を表示したり、本の個別情報を表示したりしたい場合、こんな風にURLを作ったりするよ

どんぶラッコ

/url HTTPメソッド … 役割
で列挙してみるね！

• /books GET … 本の一覧表示
• /books POST …. 本の新規作成
• /books/{id} GET … 本の個別情報表示
• /books/{id} PUT … 本の個別情報表示
• /books/{id} DELETE … 本の個別情報削除

グランくん

なるほど、 URL が 主語、 HTTPメソッドが動詞のような役割をしているんだね！

どんぶラッコ

その通り！ “どこ” に “なに” をする、が明瞭になるので多くの現場で使われています

戻り値はどうしたらいいの？

グランくん

REST APIについてはなんとなくわかってきたから実装してみよーっと

グランくん

ちなみに、GET の時のレスポンスは 一覧や個別の情報をリターンすればいいってわかるけど、 POST や PUT, DELETE の時はレスポンスデータはなにを返したらいいの？

どんぶラッコ

それは2つの考え方があるよ

どんぶラッコ

まず一つ目は更新したデータを return する という方法。こんな風にデータが直りましたよ、というのを示してあげる方法だね

どんぶラッコ

もう一つが HTTP STATUS で 201 や 204 を返してあげる方法。201 は “情報が作成されたよ！”という意味、204は “通信は成功してるけど戻り値がないよ！”という意味です。

どんぶラッコ

どちらの方針であったとしても DELETE は 204を返しますね。データを削除してしまっていてなにもない状態なので！

グランくん

さっきから出てきてる 204 という数字は HTTP レスポンスステータスコードと呼ばれるやつですね！

どんぶラッコ

(知ってたんかい)

No Content についてはこのように定義されています。

ちなみに、POST で 情報を作成した時には HTTP Header の Locationに 作成された URLを含めるとよりベターです。

疑問の解消につながれば嬉しいです！