API開発で注意すべきデータ形式について

本日、とあるツイートがTLに流れてきました。

上記について、昔プロジェクトで話題になったことを思い出しました。
API開発時に気を付けるべき点として、上記が良くない理由を理解しておく必要があります。

具体的にどこがよくないのか

下記で説明していきます。

データ形式に一貫性がない

上記APIのデータ形式を整理すると、下記の通りです。

• 単一のアイテムを返す場合、{"item":"hoge"} のように直接値を返します。
• 複数のアイテムを返す場合、{"item":["hoge","fuga"]} のように配列を返します。
• 0件の場合は空のオブジェクト {} を返します。

このように返されるデータの形式が条件によって異なります。
そのためAPIを使用する側では、受け取ったデータが「単一のアイテムなのか」「アイテムの配列なのか」「空なのか」を毎回確認しなくてはなりません。
後述しますが、エラー原因をわかりにくくする原因にもなります。（動的型付けだと最悪）

エラーハンドリングが難しい

エラーに対するハンドリング処理が難しくなります。
上記APIでは、0件の場合に空のオブジェクトを返していますが、以下のようなレスポンスパターンが考えられます。

• 実際にデータが0件
• データが取得できなかった

上記のように正常に空のオブジェクトが返されているのか、エラーが発生しているのかの区別ができません。

改善方法

常にアイテムを配列で返し、データ形式を一貫させます。

• 単一のアイテムを返す場合、{"item":["hoge"]}
• 複数のアイテムを返す場合、{"item":["hoge","fuga"]}
• 0件の場合、 {"item":[]}

あとは、エラーが発生時にエラーメッセージやステータスコードを付与したいです。
欲を言えば、メタデータを追加して何件取れたかもわかるようにしたいですね。

まとめ

継ぎ足しで作ったタイプのレガシーシステムで実際に見かけたことがあるAPIの解説でした。
もし懸念点に不足があれば、コメント等で教えていただけると幸いです。