エンタープライズAPIに求められる8つの要素

今回はエンタープライズレベルでのAPIを提供する上で注意したいことを挙げています。今後BtoBなどのエンタープライズ領域においてAPI活用が進む中で、以下列挙した点に注意しておくと関係者にとって使いやすいAPIが提供できるはずです。

1. APIの仕様・ルールを統一化する

APIによってインタフェースやデータフォーマットがバラバラだと、利用者を混乱させ結果としてAPIの利用促進に繋がりません。
業界標準は存在しませんが、近年ですとインターフェースはRESTで、データフォーマットはJSONもしくはXMLで、その他以下にも記載があるバージョン管理やパラメータの命名規則など必要最低限のルールを社内で整備してAPIを提供するようにしましょう。

2. 権限管理

権限管理はエンタープライズ用途でAPIを利用する場合において特に重要です。

通常、APIは一つのトークンを一人のユーザ、または一つのアプリケーションから利用する想定になっているかと思います。しかしエンタープライズにおいては複数の組織（ユーザ）が混在した環境でのAPI利用が前提となります。

そのため組織やユーザごとにデータのCRUD（参照、作成、更新、削除）に対する権限を指定できるようにしておく必要があります。例えばA組織に所属するユーザに対してはデータの参照は許可するが、更新はできないようにするなど、企業のシステム管理者がAPIに対する権限を設定できるようにしておく必要があるでしょう。
弊社ではAPIへのアクセスを安全かつ柔軟にコントロールできる権限管理機能を今年９月より提供しています。
権限管理 IAM APIに関する情報はこちら

3. ロギング

APIのコール回数レベルであれば提供しているところはあるかと思いますが、企業利用においてはAPI単位であったり、ユーザ単位でどのデータにアクセスしたか、どんな操作を行ったかが記録されている必要があります。それは監査上必要であったり、インシデントが起きた際の検証用としても重要です。

APIはシステム間連携が多いため、見た目に分からないところで操作が行われたり、深夜のバッチ処理で一気にデータの操作が行われます。そのため適切なレベルでのロギングが必要でしょう。

4. SLAおよびメンテナンス時の対処

APIは自動で処理が行われますが、それでも絶対に落ちないものではありません。また、定期的なメンテナンスが行われることもあるでしょう。そのためAPI側でもSLAであったり、メンテナンス時に返すAPIについてきちんと取り決めがあるべきです。

取り決めがない場合、単純に500系エラーを返してしまってAPIを利用しているサービス側でもエラーが発生してしまいます。そうなると担当者などにエラーメールが押し寄せるなんてことも少なくありません。適切なエラー情報が提供されることで利用側でもエラー時に対応した実装ができるでしょう。

5. バージョン管理

エンタープライズにおいては特にAPIのアップデートは慎重にあるべきで、一定の指針を設けた上で適切なバージョン管理を行いましょう。通常、APIのエンドポイントの中にあらかじめバージョン番号を仕込み、新旧バージョンを区別します。システムによってはすぐに新バージョンのAPIに対応できないケースも想定されるので、新旧バージョンを平行して運用できるようにしておくべきでしょう。

6. ドキュメント

意外とAPIのドキュメントが不足しているケースは少なくありません。提供側としては十分と考えていても、利用側に立ってみると全く足りないことが多々あります。単に正確に書けば良いという訳ではなく、十分に過不足なく、利用者にとって使いやすいドキュメントを心がける必要があります。

ドキュメントはなるべくオンラインで公開する方が良いでしょう。専用の検索サーバを立てたとしてもGoogleなどの検索エンジンに敵うものではなく、利用者にとって使いづらいことが多いです。また、PSDなどだけで配布するのも検索性という意味において良いとは言えません。

7. ライブラリ/SDK

ドキュメントと同様に気をつけたいのがライブラリやSDKです。APIを提供するだけでは意味がなく、各種プログラミング言語に対するライブラリ/SDKが必要です。まず提供側にとって使って欲しい環境向けに提供しますが、それ以外にも各種言語に対してライブラリ/SDKが必要でしょう。企業システムは一つの言語だけで作られている訳ではなく、多くのライブラリ/SDKが必要です。

後々のメンテナンス性を考え、なるべくライブラリ/SDKはAPIを薄くラッピングするだけに心がけるべきです。また、ライブラリ/SDKについても十分なドキュメントやサンプルアプリなどを準備しておく必要があります。

8. サンドボックス

最後にAPIを使うためのデモ環境を用意しましょう。いきなり本番環境を使ってデータを更新したり、削除するというのは利用企業にとって大きなリスクになります。なるべく本番に近いデータを自動で用意してあげたり、現状の本番環境のデータがコピーできるようになっていると理想的です。また、メンテナンス時のテストもできるようになっていると良いでしょう。

APIを使った開発は一度終わったら完了ではなく、継続的に更新したり追加開発を行うものです。サンドボックス環境も30日限定などではなく、いつでも常に使えるようになっている必要があるでしょう。

APIの利用を社内に限定するだけでなく、社外に公開してビジネス展開する場合には、上述したポイント以外にも留意すべき点は多いと思います。特に従来企業内にあったデータを解放するとなった場合、それまでとは全く違うレベルでの運用が求められるはずです。

単に公開すれば良いという訳ではなく、周辺技術や利用企業の開発/運用利便性を考えた上でAPIを提供しなければなりません。