現場の事例から学ぶAPI設計の勘所

　近年、API Economyの広がりとともに、APIを公開する企業が増えている。しかし明確な方針を決めずにAPI公開を進めたがゆえに、その後の継続的なAPI開発・運用でコストの増大を招いたり、利用者の満足度が低下するなどの例も見られる。

　本稿では、API開発・運用の標準化方針を策定した事例をベースに、API設計でのベストプラクティスとHints＆Tipsを紹介する。

 

 

　API標準化が求められる背景を理解するに際して、現在のAPI公開の動向を振り返ってみよう。ProgrammableWebの「APIs show Faster Growth Rate in 2019 than Previous Years」では、次のように述べている。

 

　Since 2005, we’ve seen APIs grow from a curiosity to a trend, and now to the point where APIs are core to many businesses. APIs have provided tremendous value to countless organizations and developers, which is reflected in their continued growth.

 

 

 　このことから、公開されるAPI数は年々増加し、企業のAPI公開が当たり前の時代に突入したと言える。また、SmartBear社が公表している調査レポート「The State of API 2019 Report」では、次のように述べている。

 

　When we asked respondents to share the top API technology challenge they want to see solved in the coming years, standardization was the #1 response, with 58% of responses. The need for standardization seems to be increasing, as standardization ranked third on the list of challenges organizations wanted to see solved in the 2016 State of API Report. Two of the other technology challenges that organizations want to see solved include versioning and re-use, which can also play a role in how organizations standardize API development processes at scale.

 

 

　この結果から、数年前に公開したAPIを今後どのように開発・修正・運用していくかが課題であると考えられる。また同レポートでは、次のようにも述べている。

　While only one-third of respondents say they currently have an internal style guide, 32％ say their organization plans to introduce one.

 

 

　このことから、API開発での標準化の重要性が認識されていると言える。

　一方、ガイドを策定しても、それをどう遵守するかは依然課題として残る。標準化の策定に伴い、社内全体で遵守するための推進体制も必要である。

 

　次に、標準化を実現するメリットを整理する。本稿では、API標準化を「同一組織が提供するAPIにおいて方針や設計を統一し、一貫性をもたせること」と定義する。

 

　設計開発から運用まで方針を統一することで、API提供側としてはタイムリーに開発したAPIを公開でき、シンプル化した保守作業により運用時のリスクを減らせるので、全体的な効率性が上がる。

 

　一方、API利用側としては、設計が統一された使いやすいAPIは学習コストが低く、アプリケーション開発が容易になるので、利用時の満足度が上がる。

 

　これがさらなる利用につながり、利用フィードバックからの改善により、品質を一層向上させたAPIが提供されるというポジティブなサイクルが生まれる。

　このように標準化を進めることは、提供者と利用者の双方に多くのメリットをもたらす。

 

 

　続いて、目標と現状のギャップから生まれる問題を整理する。

 

　APIは自社製品であるという考え方に基づくと、従来のソフトウェア開発と同様に、API利用者・提供者の双方の観点から、あるべき姿を考える必要がある。

 

　双方から見て、満足度が低く、利用数も低い、開発運用負荷が高いなどと言った現状がある場合、考えられる問題として、インターフェース設計が統一されていない、運用方針が定まっていないなどの点が挙げられる。

 

　これらの問題に対する解決策として、方針や設計を統一し、一貫性をもたせること、つまり標準化のベストプラクティスに従うことが考えられる。

 

　ここで、実際の事例を簡単に紹介する。あるユーザーでは、企業グループ間・グループ内で一貫した開発・運用方針が定まっていないという課題があった。大きく分けて、開発フェーズではパス設計方針・バージョン付方針が統一されておらず、これによりグループごとのAPIが統一感に欠け、API利用者にとっては学習コストが上がり、API管理者にとってはオペレーションミスにつながるなど、混乱が生じていた。

 

　また運用フェーズでは、バージョン管理がされてない、リリース手順が決まっていないことから、APIごとに運用が異なる煩雑なプロセスとなり、オペレーションミスを招いていた。

 

　こうした問題から考えられるAPIの開発・運用の課題は前述のように、標準化、つまり方針の統一と一貫性を図ることで解決できると考えられる。

 

　この事例の場合、検討項目の例としてバージョン付・パス設計方針、リリース手順の統一、バージョン管理手法の統一、責任所在の明確化いったことが挙げられる。

 

　開発運用を進める最初の段階で標準化を検討しないと、運用を進めるうえでさまざまな問題が発生するので、ぜひ標準化を検討してほしい。

 

 

　前述の課題に対応するため、3つの標準化の取り組み（開発標準、運用標準、推進体制）について紹介する。APIの設計から開発、テスト、公開といったライフサイクル全体を想定して、API標準化を検討することが重要となる。

 

　それぞれの検討での成果物としては、各種ガイドや自動化のためのツールなどが挙げられる（図表1）。

 

 

・URL全体をシンプルにわかりやすくする
・リソース名は名詞形（複数形）とし、結合する際はハイフン（-）とする
・バージョン表現では、後述するセマンティック・バージョニング表現に基づいてメジャー・バージョンをパスに含める

 

　次に、パス設計でバージョン付が統一されないという課題に対しては、セマンティック・バージョニングを採用するのが一般的である。これは、以下のように3つの数字（x、y、z）でバージョンを表現する方法である。

 

x-メジャー：後方互換性のないAPI仕様変更
y-マイナー：後方互換性のあるAPI機能追加
z-パッチ：後方互換性のあるバグ修正

 

　このようなベストプラクティス情報だけでは、自社に有効か、例外がないかといった疑問があるかと思う。そこで、開発標準化ガイドを策定したユーザー事例を紹介する。

 

　このユーザーでは、コールセンター向けの社内フロントエンド・システムの刷新に伴い、バックエンドのMQとのインターフェースをAPI化することになった。

 

　内部でのプロトコル変換は、IBM App Connect Enterpriseで対応した。この事例では、IBM App Connect EnterpriseでのAPI実装の事前開発として、APIの仕様をSwagger文書として作成した。

　今回は、Swaggerファイルを手作業で開発する方針となったので、開発ガイドを策定することにした。このガイドでは、ユーザーの既存の開発規約やMQインターフェース仕様書をベースに各種ルールを決めている。

 

　開発ガイドを策定するなかで検討したポイントを、以下に2つ紹介する。

　1つ目は、REST原則準拠の方針についてである。結論として、このユーザーでは、REST原則からの例外として、参照系APIでもPOSTを選択することになった。これはバックエンドがMQの場合、参照処理でも多くの要求パラメータが必要となり、いくつか課題が出ると想定されたためである（図表2）。

 

 

 

　2つ目は、パス設計の詳細化方針である。API化の対象となるバックエンド機能、ユーザー企業の組織や文化を考慮して、シンプルでわかりやすくするルールを検討した。その際には、以下の観点でAPIパスの一覧を作成し、ユーザーレビューに基づき決定していった。

 

・MQインターフェース機能がイメージできる単語または命名規則か
・将来的な変更、追加等で問題が出ないか

 

　検討の結果、パス設計の方針は、以下とした。たとえば、顧客情報に関するサービス一覧を参照するAPIの場合は、「/v1/customer/service-list」としている。

 

・URL階層
・基本構造は「/バージョン/対象情報/API名/操作名」とする
・メジャー・バージョンをパスに含める
・対象情報は顧客、契約、請求などサービス内の対象情報
・API名はサービスを明示する情報
・操作名は参照、更新などを明示したい場合の情報（オプション）
・リソース名
・業務情報をイメージしやすい単語を選定
・長くなったら「-」で結合する

 

 

　2つ目の取り組みは、運用標準である。この方針では、開発段階を含めて運用標準化のルールを決めることが求められる。ここでも前述した課題に紐づく一例を紹介する。

 

　バージョンが管理されておらず、ソースのデグレードや修正ミスが起きるような課題をなくすために、ソースファイルの管理、バージョン管理の方法を決める。

　またリリース手順が決まっておらず、担当者間の混乱や作業ミスが発生するという課題をなくすために、リリースの手順や担当者の役割を決め、かつ自動化方法を決めることが大切である。　

 　さらにAPIの開発・運用の方針検討では、DevOpsチームの実現を目指して、以下の点を考慮して決めるとよい（IBM提供のガイド「DevOps for DUMMIES」も参照してほしい）。

・人の生産性を高める（たとえば役割決めやコミュニケーション手段の確立）
・プロセスを最適化する（たとえば無駄な作業手順やコミュニケーションを避ける）
・ツールを選択・活用する

 

　これらを前提に、運用方針を策定したユーザー事例を紹介する。このユーザーでは、バックエンドのMQ機能をIBM zOS ConnectでAPI化し、IBM API Connectで社内利用者、社内システムへ公開・管理している。

 

　この事例では、Swaggerソースファイルやそのバージョンの管理方針を決めた。また、開発・リリースまでの手順・プロセスを決め、自動化ツールを活用した。運用ガイドを策定するなかで検討したポイントを、以下に2つ紹介する。

 

　1つ目は、ソース管理の方針である。ソースの開発段階から、自動化ツールを活用することで作業効率・保守性を高めた。Swaggerの作成方針として、メインとなる名前、パス、メソッドなどの構造と、要求・応答のデータ構造を定義したファイルに分割することとした。

 

　これは、1つのファイルにするとサイズが大きくなり、メンテナンスが煩雑になるためである。これらの参照構造のもととなるメイン構造のテンプレートや、参照先のデータ構造は、自動生成するためのツールを開発している。

 

　データ構造は、Excelの仕様書から自動生成するツールを開発した。さらに、環境依存のバックエンドURLの情報などは、ランタイム上で管理することで、1つのソースファイルを複数の環境で利用できるようにした。

 

　開発したソースや仕様書は、ソース管理サーバー上で管理し、申請によって登録・貸出を管理した。このような方針によって、ソースの修正ミスやデグレードの発生を防いでいる（図表3）。

 

 

 

　2つ目は、リリース管理の方針である。リリース管理については、ソース管理サーバー上のソースやリリース定義を各環境の運用サーバーに配布し、運用サーバー上のシェルやスケジューラを使用して自動リリースした。基本的な方法ではあるが、手順ミスや作業負荷を軽減している（図表4）。

 

 

 

　これらのソース管理、リリース管理では、API開発者とAPI運用者の間で事前に決めたプロセスに沿って作業を進めるとともに、随時、ユーザー企業内のコミュニケーションツールを活用して情報連携、プロセス管理を実施している。

 

　ここまで開発標準、運用標準の取り組みを紹介してきたが、参考として、図表5にプロジェクトでよく検討する開発・運用ガイド、自動化ツールのポイントをまとめる。事例で紹介していない項目もあるが、APIの利用者や、ユーザー環境によって検討したほうがよいと考えられる項目もあるので確認してほしい。

 

 

 

 

 

　3つ目の取り組みは、推進体制である。ここまで紹介した開発・運用の標準化のルールだけでは、実際の現場で以下のような状況が発生すると考えられる。

 

・標準化ガイドが参照されない、準拠されない
・標準化ガイドに準拠したつもりでも、客観的に見ると準拠していない
・標準化ガイドは参考にしているが、ガイド外の内容を各担当者が判断して進めている

 

　そのため、標準化の方針策定だけではなく、それを推進するための体制も重要となる。ここでは実際に推進体制を検討したユーザー事例を紹介する。このユーザー組織には業務部、システム部などさまざまな部門・課があり、縦割りの組織文化のため、部門を越えたガイドラインの展開が難しかった。

 

　そこで、各部門・課からメンバーを招集し、組織を横断したAPIガバナンスボードを設置した。この活動には、日本IBMのGBSコンサルティング、日本アイ・ビー・エム システムズ・エンジニアリング（ISE）の技術支援のメンバーが関わって取り組みをサポートした（図表6）。

 

 

 

　APIガバナンスボードの活動では、組織横断的に意見を収集しながらガイドラインを策定し、API標準化を推進している。またAPIについての認識を高め、利用をより推進するための社内外への啓蒙活動も実施している。

 

　API標準化を推進する取り組みとしては、API開発や運用の各ライフサイクルの節目で、ガバナンスボードによる以下のような確認・承認・判断を行っている。

 

・設計開始時にガイドラインに準拠しているかを確認
・サービス提供開始時にAPIのテスト結果や、運用手順に問題がないかを確認し、APIの外部公開を承認する

API運用　　

・サービス提供開始後にAPIの利用状況を評価し、サービスの継続を判断する（あまり使われていなかったり、問題があれば廃棄などの判断を行う）

 

　これらの取り組みによって、APIの開発・運用のライフサイクルにおける標準化遵守を維持している。

 

　以上本稿では、APIを効果的に公開するための3つの取り組み（開発標準、運用標準、推進体制）について、事例を交えながら取り組みのポイントを紹介してきた。

 

　後先考えずにAPIを公開すると、さまざまな課題が出て、APIの利用数・満足度が低下し、作業に多大なコストや工数が必要な状況を招く。そのような事態を避けるため、今回紹介した方法を採用することで、よりAPIが利用され、満足度が向上し、コストを低減するなど、あるべき姿へ誘えると考える。ぜひ、ユーザー環境に即した標準化方針を決めてほしい。

 

---

 

日本アイ・ビー・エム システムズ・エンジニアリング株式会社
クラウド・プラットフォーム
アドバイザリーITスペシャリスト

 

2008年に日本IBM入社。入社以来テクニカル・セールスとしてWebSphere Application Server、IBM Cloud といったアプリケーション基盤製品、クラウドサービスの技術支援に従事。その後、日本アイ・ビー・エム システムズ・エンジニアリングに出向し、現在はIBM API Connectを中心としたAPI管理基盤の設計・構築に携わっている。

 

 

････････

 

日本アイ・ビー・エム システムズ・エンジニアリング株式会社
クラウド・プラットフォーム
アドバイザリーITスペシャリスト

 

2009年に日本アイ・ビー・エム システムズ・エンジニアリング入社。入社以来、IBM製品スペシャリストとして、基盤製品やAPI Connectなどのシステム連携製品に関して、お客様プロジェクトでの要件定義・設計・構築フェーズ支援、技術支援を担当してきた。近年は、システム方針、製品選定に関する上流検討に携わっている。