開発していてエラーは常に発生します。エラーが一度も出ずに、すべての開発が終えられることなど皆無です。その多くは開発者のコードに起因しますが、だからといって「勝手に直して」と突き放して良いわけではありません。自分のコードが悪いと分かっていても、それでも繰り返しエラーが出たりするとうんざりしてしまいます。特にそれが第三者の作っているWeb APIであったり、SDKやライブラリを使っている場合です。使いづらい、どう使ったら良いか分からないようなライブラリを誰が使い続けたいと思うでしょうか。

DevRelを考えるような人たちは基本的にWeb APIやSDK、ライブラリを提供する側にいるはずです。開発者は大変な苦労をしてまで自分たちの製品を使ってくれると思わない方が良いでしょう。最近では同じようなWebサービスがたくさん出てきています。ちょっと試してエラーが出て、それが解決できないとなったら、すぐに諦めて別な製品を使い始めてしまうはずです。

繰り返しになりますが、エラーが出るのは避けて通ることはできません。問題はエラーが出た後のフォローアップです。しかも、コーディングしている人の傍にずっといれる訳ではありませんから、なるべく彼らが自分たちでセルフサポートできるようになっている必要があります。

まず一点目として分かりやすいエラーメッセージを返しましょう。ダメな例としてInstagramを挙げます。InstagramのAPIエラーで良く出るのが Oops an error has occured です。これは本当に意味が分かりません。エラーが出た、なんて誰だって分かっているのです。問題はどう解決したら良いかを提示することです。

良い例としてSquareを挙げたいと思います。このエラーは本当にすごくて、どの部分でエラーなのかが一目で分かります。以下の場合、 line_items は配列になっており、その1つ目のデータの名前が抜けているということです。

{
  "errors":[{
    "category":"INVALID_REQUEST_ERROR",
    "code":"MISSING_REQUIRED_PARAMETER",
    "detail":"Missing required parameter.",
    "field":"line_items[0].name"
  }]
}

これくらい分かりやすいと開発者は自分のコードを見直して、すぐに生産的活動に戻れるようになるでしょう。

エラーのレイヤー

次に考えたいのがエラーのレイヤーです。Web APIを提供している場合、3つのレイヤーでユーザと接することができます。

• IDE連携
• SDKによる検証
• APIのレスポンス

まずIDE連携です。これはスクリプト言語だと難しいかも知れません。EclipseやXcode、Android StudioなどであればSDKやライブラリをインポートすると、入力補完ができるようになります。そこでどういったデータを与えれば良いのか説明できます。大抵、それらのメッセージはJavaDocなどのドキュメンテーションシステムでも使われて、HTMLとしてオンラインで閲覧もできます。

次にSDKによる検証です。SDK側であらかじめ入力値をチェックして問題がある場合はエラーを返すようにします。これによってユーザはネットワークアクセスすることなく、素早くエラーを確認できます。ネットワークを叩いてレスポンスを待つというのは意外とストレスです。なるべくネットワークへのアクセスを必要とせず、エラーを返すべきでしょう。

それでも解決できなかった場合はAPIのレスポンスで確認することになります。これはメールアドレスのユニークチェックであったり、サーバ側との連携が必要な場合は致し方ありません。そうでない場合はなるべくSDK側でエラー処理しましょう。

SDKでの検証を楽にする方法としてJSON Schemaなどを使ってSDKとサーバで共通の入力チェックを用いる方法があります。これによってSDKのメンテナンス工数を減らせるようになり、SDKとサーバ側とで入力チェックにずれがなくなります。

APIでの検証は、運営側にとってはコントロールしやすいというメリットがあります。とは言え、開発者目線で考えた時にはなるべく彼らに近いレイヤーでエラー内容を確認できるようにすべきです。

エラーが起きるのは決して悪いことではありません。むしろ、それをきっかけとして開発者とのコードを通じた対話がはじまると言うこともできます。エラーを素早く解決できるように促すことで、開発者の生産性を損なうことなく、製品を使い続けてもらえるようになります。その使いやすさはロイヤリティの向上につながり、DevRelの大きな成果になるでしょう。