share facebook facebook twitter menu hatena pocket slack

2018.10.03 WED

api blueprintでData Structuresを利用する際の注意点

甲斐 甲

WRITTEN BY 甲斐 甲

概要

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はオブジェクトで返すわけですが、オブジェクトの内容は同じになります。
今回はサンプルなので、idname しかないですが、実際はもっと項目は多いわけで。。。
あとは分かりますよね。。。

# 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

元記事はこちら

api blueprintでData Structuresを利用する際の注意点

甲斐 甲

甲斐 甲

2018/7にJOIN。 最近の好みはサーバレスです。なんでもとりあえず試します。

cloudpack

cloudpackは、Amazon EC2やAmazon S3をはじめとするAWSの各種プロダクトを利用する際の、導入・設計から運用保守を含んだフルマネージドのサービスを提供し、バックアップや24時間365日の監視/障害対応、技術的な問い合わせに対するサポートなどを行っております。
AWS上のインフラ構築およびAWSを活用したシステム開発など、案件のご相談はcloudpack.jpよりご連絡ください。