これからAPIを公開しようと考える企業は多いはずです。APIは単に作れば良いわけではなく、周辺の情報も一緒に整備していく必要があります。それらが抜け落ちると誰も使ってみようと思わないでしょう。
今回はAPIを開発する際に最低限チェックしたい6項目を紹介します。APIを公開する際にチェックしてもらうとよりスムーズな立ち上がりが期待できるでしょう。
APIフォーマット
まず当たり前ですがAPIを作成しなければなりません。最近の流行としてはURLとHTTPメソッドを組み合わせたRESTful APIが人気です。各URLが個別のリソースを特定します。よく知られた仕組みを取り入れるのは開発者の体験を向上させるという点において重要です。
もちろんこれは利用目的によって異なります。例えばWebSocketの場合はURLが異なりますし、RPCであったりGraphQLで提供されるAPIは形式が異なります。とは言え、そういった技術を使う場合においてもデファクトがありますので、そうした手法を取り入れましょう。
認証
認証を伴わないAPIはまず存在しません。種類としてはBasic認証やトークン認証といった簡易的なものに加えてOAuth2/OAuth1/証明書などの認証があります。この技術の選定はAPIを誰向けに、どう提供するかによって変わってきます。
ユーザが自分のデータを操作するために提供される場合はOAuth2が一般的になっています。サーバ同士の連携ではトークン認証でも良いでしょう。シークレットキーと呼ばれる、漏洩すると不正利用される情報を伴う場合はWebブラウザ上で使えるようにするのは問題があるでしょう。
アクセス制限
アクセス制限として一般的なのは多数のアクセスに伴うバンです。APIの場合、プログラミングの組み方によっては大量のアクセスが発生することがあります。そうした時にサーバであったり他のユーザへのレスポンスを維持するためにアクセスを遮断することがあります。きちんと明文化されている場合もあれば、大きな負荷を与えた場合と言った書き方をすることもあります。
利用者によって利用できる機能を制限する場合、管理画面などを使ってアクセス制御を行います。AWSの場合、IAMという認証サービスによってアクセスできるリソースの制限ができます。この場合はユーザ、アクセス先、可能なアクションという三つの要素で制御されます。
CORS
JavaScriptの場合、アクセスできるホストはlocalhostに限定されます。この制限を超えてAPIを利用できる仕組みがCORSです。これはサーバ側で設定しなければなりません。JavaScript（Webブラウザ）からAPIを利用できるようにするならば、CORSの設定は欠かせません。
なおCORSはすべてのアクセス元からの利用を許可する訳ではありません。開発するアプリケーション単位で制御することもできます。エンタープライズでの利用であれば、CORSでアクセス元を制御するのが良いでしょう。
ドキュメント
開発者向けのドキュメントは重要です。ドキュメントがなかったら誰も使ってみようと思わないでしょう。しかしドキュメントは作成やメンテナンスに大きなコストがかかります。あまり作り込み過ぎないのが良いでしょう。
最も大事なドキュメントはAPIとチュートリアルになります。最初の利用までのステップを簡単に行えるようにすることで最初の利用者を掴めるようになります。その上で徐々にドキュメントを充実させていけば良いでしょう。
SDK/ライブラリ
APIをそのまま実行するのは意外と面倒です。特にOAuth2で署名を生成するのは面倒で、開発工数もかかります。面倒だと利用者も伸びないでしょう。そこで開発元としてSDKやライブラリを用意するのが一般的です。APIがブラックボックス化されれば開発者はAPIを意識せずに利用できます。
ただしSDKを提供するプログラミング言語の選定が必要になります。エンタープライズであればJavaやC#の優先順位が高くなるでしょう。スマートフォンかデスクトップかによっても異なります。将来的なメンテナンスコストも考えた上で選定しなければならないでしょう。
APIを作って公開するだけであれば簡単です。問題は使ってもらえるか、使いやすいAPIにできるかです。セキュリティも制限もなければ、利用するまでの敷居は低いかも知れません。しかしセキュリティやプライバシーに配慮されていない仕組みでは安心し手利用はできないでしょう。そうした観点も必要です。
さらにドキュメントであったり、ライブラリのような開発者がスムーズに利用をはじめられるための仕組みも用意しなければなりません。いきなりすべてを作るのは難しいので、定期的にアップデートしながら進めていくのが良いでしょう。APIは公開して終わりではなく、継続的な更新が肝心です。
