課題の多いAPIの設計・運用、うまく活用するためのポイントとは
このようにさまざまなビジネス上の効果を生み出すことのできるAPIだが、その設計・運用に関して、課題を抱えている開発者も多い。
Postmanでは毎年、定量的に世の中の声を拾うべく大規模なユーザーサーベイを行っている。そのレポートが「State of the API Report」だ。
同サーベイでAPIの利用障壁として最も課題として挙げられているのは、ドキュメントに関するものだ。「API仕様書が分かりにくい、読みづらい、書き方がバラバラで一貫性がない。さらにドキュメントがないこともある」と川崎氏は指摘する。これでは開発者体験の低下を促し、インテグレーションコストにも大きな影響を与えてしまう。
2番目に課題として挙げられるのが、APIがどこにあるか分からないという問題だ。「ある部署が○○というAPIを作ったが、他部署にまでその存在が知られておらず、同じような機能を持つAPIを作ってしまった、といったことが起きがちです。日本の会社の組織はサイロ化していることが多く、よくある課題ですが、会社全体で見ると大きなロスです」（川崎氏）
その他にも、APIで外部からの呼び出しを受け付けることによるセキュリティ面のリスクなど、さまざまな課題があるという。
現在のアプリケーションに求められる要件に対応していくには、これらのAPIの課題を解決し、ユーザーにとって分かりやすくするのはもちろん、AIとの連携もしやすいAPIの設計・運用がカギを握る。そのコツはあるのか。
草薙氏は「人間に対してもAIに対してもフレンドリーなAPIを設計・運用するコツは大きく変わらない」と前置きし、次の3つのポイントを示した。
第1のポイントはAPIの利用に際して必要十分な情報とその機能が明確に記述されたドキュメントを用意すること。
ユーザーだけでなくAIに対してもドキュメントが必要なのかと思うかもしれない。確かに生成AI以前のプログラムからの利用であれば機械用記述やカタログなど、機械用に最適化されたものを用意する必要があった。だが最近の生成AI、例えばOpenAI APIのFunction callingは、外部システムとの連携がミスなくできるようになる仕組みであるが、機能仕様（JSONデータ）の中の自然言語による説明を元に連携が適切かどうかを選択する。「インプットを自然言語で行うという人間に近い形となっているので、ドキュメントは重要です」（草薙氏）
2点目のポイントは、標準的なやり方に沿った設計を理解すること。「OpenAPIと呼ばれるAPIの世界の標準仕様に沿った形でAPIの定義と説明を記述すれば、ツールも揃っているのですぐ開発に取りかかれますし、バージョンが上がっても容易に管理することができます」（草薙氏）
3点目のポイントは、APIに関する情報を一か所にまとめること。APIはバージョンアップなどにより仕様変更が多く発生する。APIを活用する際の課題として「いま参照している情報は信頼できるものか」といった迷いが生じてしまうこともあげられる。APIを提供する側としても、せっかく作ったAPIをユーザーが存在を知らなければ使ってくれない。「ここに行けばメンテナンスされた最新の情報が詰まっている、というデータベース的なものを用意することが重要です」（草薙氏）
