API設計で気をつけて欲しいこと

はじめに

僕は今アプリエンジニアとして働いているのですが、渡されるAPIがアプリで扱いづらいとなることがちょこちょこあり、
これはきっとアプリでどのようにAPIを使っているかを知らないからこんなことになるのだ！と断定し、サーバーを開発してる人たちにそこらへんを知ってもらおうと記事を書くことにしました。

レスポンス編

アプリは静的言語なので、APIのリクエスト/レスポンスは全て構造体で定義しています。(現場による)

例えばAPIのレスポンスで

{
    "todoList": [{
        "title": "魚をさばく",
        "memo": "マグロと包丁は準備済み"
    }]
}

こんな形のものがあったとします。
その時のアプリ(Swift)では↓のような構造体を準備し、受け取ったレスポンスjsonをデコードして構造体のインスタンスに変換し使っています。

struct Todolist: Codable {
    let todoList: Todo

    struct Todo: Codable {
        let title: String
        let memo: String
    }
}

では困るやつです。
jsonはこちら。

{
    "todoList": [{
        "title": "魚をさばく",
        "memo": "マグロと包丁は準備済み",
        "tags": [   
            { "category": "魚" },
            { "priority": "high" }
        ]
    }]
}

tagsが追加されました。
配列になっていますが中の要素はばらばらになっているみたいです。
多分、このサーバー開発者的にはDBでcategoryテーブルとpriorityテーブルを作るよりも、tagテーブルを一個作ってKSVみたいな構造にして汎用性を高くしちゃおう！的な感じなのでしょう。

アプリでの構造体はこんな感じになります。

struct Todolist: Codable {
    let todoList: Todo

    struct Todo: Codable {
        let title: String
        let memo: String
        let tags: [Tag]

        struct Tag: Codable {
            let category: String? // この?はnullもありえるよ!マークです。
            let priority: String?
        }
    }
}

Tag の構造体を追加しました。

ほんとはCategoryとPriorityの構造体を作りたいのですが、中身を見るまではどちらになるか判別ができないためTag構造体でまとめて定義する形になってしましました。。

またpriorityを取得したい!となったときには、tagsをfor文で回し、priorityが入っているところを探さなくてはいけません。
Todo構造体にpriorityを取得するメソッドを追加すればいいのですが、なんか微妙です(/ _ ; )

まとめ

jsonのキーは可変にしないで欲しいです！！！！！！！
ほんとはリクエストについても書きたかったのですが、昔遭遇したリクエストに困るAPIの詳細が全然思い出せませんでした。。逆にどう作ったんだ。。

（あと、RDB使ってるならテーブル構造をKSVっぽく保存しないで欲しいです！！API扱いづらいし、データの中身見るまでどんな値が保存されるか分からないから微妙だと思うよ！）