デザインだけじゃない！適切なAPI設計によるユーザー体験向上 part.2　間違ったAPI設計が招く罠…

はじめに 〜本記事について〜

前回の記事では主に以下について解説し、ユーザーエクスペリエンス（以下「UX」）の向上にはAPI設計も重要であることをお伝えしました。

・APIとは何か
・API設計の進め方
・API設計の失敗事例と改善事例

今回は、システム・アプリ開発でAPIを利用するユーザーの視点に立ち、技術的な部分にも少し踏み込みながらAPI設計者としてユーザーが”使いやすい”と感じるAPIを設計するためにはどういった点に配慮していくと良いかを解説します。

なぜか使いにくいAPI

WebサービスをAPIを通じて利用するとき、「このAPI、なにか使いにくいな…」と感じたことのある方は少なくないでしょう。APIを利用する際にしばしば出会う、設計のアンチパターンを具体例とともに見ていきます。

中身を想像しにくいプロパティ名

【どんな不都合がおきるのか？】

とある健康食品のWebサイトのお話です。
設計の際、 “i_price”の“i”を“item”ではなく“initial”の略、つまり初回購入価格の値（initial_price）と勘違いしてしまい、購入確認画面（カゴの画面）で初回購入価格として“i_price”の金額を表示させました。しかし、実際は商品単価（item_price）だったという不具合が発生。

【なぜ、この失敗が起こるのか？】

APIから返されるデータにはユーザー情報や商品情報など様々な情報が存在します。ユーザー情報であればユーザー名、郵便番号、住所、電話番号などといったデータが含まれており、このような個々のデータを「プロパティ」と呼びます。

さて、以下に挙げるプロパティは、何を表しているでしょうか。

・i_name
・i_price
・i_amount

アンダーバーの後ろだけ見ると、それぞれ何らかの名称、価格、数だと想像できます。しかし、前半部分の”i”は単語が省略されているようで、何を意味しているかパッと見て分かりません。先に答えを言ってしまうとこの”i”は”item”の略称で、つまり「商品」を意味しています。
したがって、それぞれ商品名、商品単価、商品の数量を表しています。このようにプロパティの名称がデータの内容を明確に表現していない場合、各プロパティがどういった情報を返しているのか想像できず、ユーザーに使いにくさを感じさせることになります。

バラバラなデータ型・フォーマット

【どんな不都合がおきるのか？】

「商品の購入日」入力欄に日付“2025-10-01”を入力して登録ボタンを押下すると【システムエラーが発生しました】のメッセージが⋯
これは、「商品の購入日」の日付のデータフォーマットが、API設計書で定義されているフォーマットとは異なっていたことが原因です。

【なぜ、この失敗が起こるのか？】

あるWebサービスでは、ユーザー情報を取得するAPIから返却される「ユーザーID」は数値型（例：12345）、商品情報を取得するAPIから返却される「商品ID」は文字列型（例：”12345”）となっていました。また、「ユーザーの生年月日」は”yyyy-mm-dd”形式（例：1990-01-01）で、「商品の購入日」は”yyyy/mm/dd”形式（例：1990/01/01）で返されます。

「ユーザーID」と「商品ID」、「ユーザーの生年月日」と「商品の購入日」はそれぞれ「ID」「日付」で、同じ種類のデータです。
しかし、同類のデータに対して異なるデータ型・フォーマットが設定されているため、ユーザーを混乱させやすい設計になっています。

このAPIのユーザーは、「ユーザーの生年月日」が”yyyy-mm-dd”形式なので「商品の購入日」も同じだろうと思って実装を進めました。ですが、正しくは”yyyy/mm/dd”形式だったため、アプリ側でバグが発生してしまいました。

このように、データ型・フォーマットに一貫性がないAPIは、ユーザーに実装の手間を増やす、バグの原因になるなど、ユーザビリティの低下にも繋がります。

不明瞭なエラーレスポンス

API呼び出しに失敗したとき、原因を特定し問題解決の糸口とするため、エラーレスポンスの明確な定義は重要です。しかし、このエラーレスポンスが曖昧だと、ユーザーはなぜAPI呼び出しに失敗したのか分からないままになり途方に暮れてしまいます。

以下のようなエラーレスポンスから、あなたはエラーの原因を推測できるでしょうか。

このエラーレスポンスは、単に「エラーが発生した」ということしか伝えていません。入力データに誤りがあったのか、認証情報が不足しているのか、サーバー内部で予期せぬエラーが発生したのか…このエラーレスポンスから原因を特定することは難しいでしょう。なかなかエラーを解消できず、ユーザーはそのAPIを利用するのを諦めてしまうかもしれません。

適切に分割されていないAPI

前回の記事において、類似データは一回のAPI呼び出しで取得できるようにすることにより、ネットワーク負荷等が軽減しユーザー・サーバーの双方でストレスが緩和されると解説しました。
ですが、単純にAPIを呼び出す回数を少なくすれば良いというものでもありません。本来切り分けられるべき情報が同じAPIに含まれると、APIの利便性が失われる場合があります。

たとえば、店舗に関わる情報を取得する「店舗情報API」があるとしましょう。このAPIのレスポンスデータに、商品分類や商品単価など商品関連の情報も全て含まれていたらどうでしょうか。
商品情報は店舗情報よりもデータ数が遥かに多いため、店舗の情報を取得したいだけにもかかわらず膨大な商品データが一緒に返ってくることでAPIからのレスポンスが遅くなるかもしれません。
また、商品情報のみを取得したい時にも「店舗情報API」を呼び出す必要があり、ユーザーの目的とAPIの目的が一致しておらず混乱してしまいます。

ユーザーフレンドリーなAPIへ

それでは、先ほど挙げた使いにくいAPIを、”ユーザーフレンドリーな”APIにしていくための改善案を見ていきましょう。

分かりやすいプロパティ名

プロパティは、そのデータが何を表しているのかを一目で理解できるように命名します。プロパティ名を考案する際は、以下のようなことに注意すると良いでしょう。

・フルスペルで記載：u_idではなくuser_idのように、単語を省略せずフルスペルで書くことで、APIの仕様書を見なくてもプロパティの意味が分かるようになります。
・命名規則の統一：プロパティの命名にあたって2語以上の単語を組み合わせる際は、2語目以降の単語の先頭を大文字にして連結させるキャメルケース（例：userName）や、アンダーバーで単語を繋げるスネークケース（例：user_name）を使用するのが一般的です。API設計時はいずれかのケースで統一することを心がけましょう。商品名はitemName、商品単価はitem_priceと表記するというように異なるケースを混在させると、APIの可読性を損なうことになります。
・冗長さの回避：user_name_of_the_personのように単語をいくつも連結させた冗長な表記は避け、user_nameのように簡潔に表記します。組み合わせる単語は、2語程度に留めるのが無難です。

一貫性のあるデータ型・フォーマット

ユーザーに提供する全てのAPIで、「ID」は数値型で統一する、「日付」は”yyyy-mm-dd”形式で統一する、というように一貫性を持たせておけば、ユーザーはデータを取得する際、同じ種類のデータの型・フォーマットの違いに悩まされることは無くなるでしょう（※ただし、明確な理由がある場合は、同類データであっても異なるデータ型・フォーマットを設定して問題ありません）。

“yyyy/mm/dd”形式で返却されたレスポンスデータをアプリ側で”yyyy-mm-dd”形式に変換する、というような実装の手間も省くことができます。一貫性のあるデータ型・フォーマットはAPIの利便性を高め、ユーザーの迅速でスムーズな開発に貢献します。

明快なエラーレスポンス

前章で例に挙げたエラーレスポンスは、ただエラーが発生したということしか読み取れない不明瞭なものでした。ユーザーが自力でエラーを解消できるようにするためには、その内容を具体的に伝える必要があります。そこで次のように改善してみました。

このエラーレスポンスは、ユーザー情報登録時に入力したパスワードの形式が正しくないことを伝えています。また、「e0001」はAPI設計者が定義したエラーコードで、API仕様書上からこのエラーコードを確認すれば、エラー内容に関してより詳しい説明を得ることができます。

適切に分割されたAPI

APIを設計する際は、そのAPIの「目的」を明確にしなければなりません。前章の「店舗情報API」には、レスポンスデータに商品関連の情報も含まれていました。これは、一つのAPI中に「店舗情報を取得する」「商品情報を取得する」という異なる目的が併存しており、いずれかのデータのみを取得したいユーザーにとっては非常に使いにくいものになっていました。

そこで、「店舗情報API」のレスポンスデータから商品関連の情報を切り出して、新たに「商品情報API」を作成しました。店舗に関わる情報を取得したい時は「店舗情報API」を、商品に関わる情報を取得したい時は「商品情報API」を呼び出すことができるようになり、ユーザーの目的とAPIの目的の齟齬が解消されてより使いやすいものになりました。

まとめ

APIは、システムとシステムの橋渡しの役割を担っています。エンドユーザーがAPIを直接意識することはほぼ無くても、この橋渡しがスムーズであればAPIを利用するシステム（アプリ）が一層使いやすくなります。
基本的にエンドユーザーが意識するのはデザイン上のUI/UXですが、その裏で利用されるAPIも適切に設計されていれば、優れたデザインの威力がより発揮されるでしょう。

この記事で紹介したポイントを意識してAPI設計を行うことが、結果的にエンドユーザーの満足度向上にも繋がります。多くの人に喜んでもらえる素晴らしいサービスが生まれることを願っています。