概要
restfulなapiを設計すっぞ。となっても、「けど同じ戻り値を何回も書きたくない!めんどくさい!」ってなりますよね。
そんなときに、Data Structuresというデータ型定義の方法が使えると知ったのですが、一部ハマったので書き留めておきます。
Data Structuresについては下記を参考にさせてもらいました。感謝!
api blueprint でData Structuresを用いてIFを定義する
https://qiita.com/haseshin/items/1394b0c70e25c9f51762
Data Structuresを利用してみる
Data Structuresを利用しない場合、/hoges
のGETはリストで、hoges/{id}
のGETはオブジェクトで返すわけですが、オブジェクトの内容は同じになります。
今回はサンプルなので、id
とname
しかないですが、実際はもっと項目は多いわけで。。。
あとは分かりますよね。。。
# hogeリソース ## hoge情報 [/hoges] ### hoge情報を取得する [GET /hoges] + Response 200 (application/json) + Attributes + items (array, fixed-type) + (object) + id : 1 (number) - ID + name : hoge (string) - 名前 ## hoge情報 [/hoges/{id}] + Parameters + id : 1 (number) - ID ### hoge情報を取得する [GET] + Response 200 (application/json) + Attributes + id : 1 (number) - ID + name : hoge (string) - 名前
で、Data Structuresを利用して戻り値をデータ型定義するとスッキリする!
というわけで、先の記事が参考になります。
api blueprint でData Structuresを用いてIFを定義する
https://qiita.com/haseshin/items/1394b0c70e25c9f51762
記事に習って、まずはData Structuresを定義します。
# Data Structures ## Hoge (object) + id : 1 (number) - ID + age : hoge (string) - 名前
hoges/{id}
の戻り値に指定してみます。
## hoge情報 [/hoges/{id}] + Parameters + id : 1 (number) - ID ### hoge情報を取得する [GET] + Response 200 (application/json) + Attributes + hoge (Hoge)
これで、戻り値はData Structuresを参照することになるので、楽で良いね!
それでは、良きapi blueprintを利用した設計ライフを^^
・
・
・
となれば良かったのですが、実際にjsonの戻り値を見てみます。
{ "hoge": { "id": 1, "age": "hoge" } }
はい。
おわかりいただけるでしょうか。。。
"hoge": { ... }
はいらないんやー。となります。
どうすればよいのか小一時間悩んだ挙げ句、下記のようにすれば良いことがわかりました。
## hoge情報 [/hoges/{id}] + Parameters + id : 1 (number) - ID ### hoge情報を取得する [GET] + Response 200 (application/json) + Attributes (Hoge)
結果を見てみます。
{ "id": 1, "age": "hoge" }
はい。
期待していた戻り値となりました。
以下がData Structuresを適用したバージョンとなります。
# Data Structures ## Hoge (object) + id : 1 (number) - ID + age : hoge (string) - 名前 # hogeリソース ## hoge情報 [/hoges] ### hoge情報を取得する [GET /hoges] + Response 200 (application/json) + Attributes + items (array[Hoge], fixed-type) ## hoge情報 [/hoges/{id}] + Parameters + id : 1 (number) - ID ### hoge情報を取得する [GET] + Response 200 (application/json) + Attributes (Hoge)
それでは、良きapi blueprintを利用した設計ライフを^^
PS) hogeに複数形はあるのでしょうか・・・知りたい
参考
api blueprint でData Structuresを用いてIFを定義する
https://qiita.com/haseshin/items/1394b0c70e25c9f51762