JSONがAPIの基本フォーマットとも呼べる存在になって久しいですが、それによって逆にJSONが持つ緩さが問題になるケースがあるようです。そのため、多くの拡張フォーマットが作られています。
今回はその一つ、JSendを紹介します。JSONフォーマットに一定のルールをつけるだけでぐっと使いやすさが増すことでしょう。
JSendの基本フォーマット
JSendのごく基本的なフォーマットは次のようになります。
{
status : "success",
data : {
"post" : { "id" : 1, "title" : "ブログのタイトル", "body" : "ブログのコンテンツ" }
}
}
明確なルールは2つです。
1. statusを持つ
APIのレスポンスを判断するためにstatusというフィールドを必ずつけます。これは3つの値を取ります。
| 値 | 説明 | 必須のキー | オプションキー |
|---|---|---|---|
| success | 処理が成功 | status,data | |
| fail | 処理が失敗 | status,data | |
| error | システムエラー | status, message | code,data |
statusは必ずありますので、それを見れば処理が成功したのか失敗したのかがすぐに分かる訳です。
2. dataを持つ
success/failの場合はdataフィールドを持ちます。処理が成功した場合には、ここにデータが入ってきますが、直接構造が入るのではなくpostのようなモデル名が入ります。もしこれが一覧の場合は次のようになります。
{
status : "success",
data : {
"posts" : [
{ "id" : 1, "title" : "ブログの件名", "body" : "ブログのコンテンツ" },
{ "id" : 2, "title" : "別なブログの件名", "body" : "別なブログのコンテンツ" },
]
}
}
data以下のモデル名があることによって、複数のモデルを一回で返すといった仕様変更があってもすぐに対応できるようになるでしょう。
削除処理のように返すdataがない場合はnullを返します。
{
status : "success",
data : null
}
dataフィールドは必ず用意するのが原則です。
エラーの場合
入力エラーなど、アプリケーション側で発生させるエラーの場合は次のようになります。こちらはdata以下に入ります。入力エラーの場合にはエラー箇所が分かるようになっていると便利でしょう。
{
"status" : "fail",
"data" : { "title" : "タイトルは必須です" }
}
対してシステムエラーが起きた場合は次のようになります。
{
"status" : "error",
"message" : "データベースに接続できません"
}
もちろん、JSONは返しますがHTTPステータスコードと組み合わせてエラーを作るべきでしょう。
JSendは制約が強くない分、導入しやすいかと思います。一定のルールに沿って提供されることで開発者にとって使いやすいAPIが提供できるでしょう。特に処理の成功、失敗、エラーが明確に分かるのは良さそうです。
