記事
Compass と Jira
カタログ
Atlassian Compass で社内 API カタログを構築
KATIE SILVER
アトラシアンのプリンシパル プロダクト マネージャー
エグゼクティブ サマリー
エグゼクティブ サマリーをここに記載
所要時間
読む時間 4 分。Compass のセットアップには 10 分もかかりません。
対象者
ソフトウェア デリバリー チームで、API を使用するユーザーが対象です。開発者、エンジニアなど、誰でもメリットを得られます。
前提条件
- Compass を入手してください。無料で試すことができ、数分で始めることができます。
正確な API カタログの作成は難しい課題
過去 10 年間で、大規模なモノリスはマイクロサービス、分散型アーキテクチャ、自律的なチームへと移行しています。メリットは確かにありますが、同時に代償も伴います。型付きコンパイラとテストが、大規模なコードベースのすべての要素が適切に連携して動作し続けるように使用されていました。現在、境界は API であり、デプロイ時にすべてが適合するかどうかは明らかではありません。
全チームメンバーが API の仕組みや変更時期を理解している場合、開発者はより迅速に作業を進め、チームはより優れた製品をリリースできます。難しいのは、ドキュメントの追跡と維持です。
サービスの詳細な計画に関しては、すべての組織の成熟度は異なります。Slack で会話して、API の作成者と利用者間で連携するチームもあれば、各 API の動作方法をサービスの作成時に文書化しているものの、その後更新していないチームもあります。適切なプロセスやツールが備わっていれば、すべての API を文書化し、その変更を他の関係者に自動的に伝えられます。
お客様がその過程のどの段階にいるかにかかわらず、アトラシアンの新しい開発者プラットフォームである Compass が役立ちます。
Compass で API ドキュメントを一元化
マイクロサービスの世界で、API ドキュメントを保存すべき場所はどこでしょうか? サービスを個別に構築・デプロイするからといって、各サービスを自己ホスト型ドキュメント サイトに保存したり、OpenAPI ファイルをわかりにくい場所に保存したりすることを求めているわけではありません。チームは、大規模な社内作業によって API レジストリを構築することなく、すべての情報をまとめて検索できるようにしたいと考えています。
Compass を利用すれば、1 週間や四半期ではなく、1 時間で API ドキュメントを簡単に一元化できます。変更を加えるたびに手動でドキュメントをアップロードする必要はありません。SCM (Bitbucket、GitHub、または GitLab) を Compass に接続するだけです。
数分以内で Compass はすべてのリポジトリをスキャンして OpenAPI ファイルを検索し、カタログに公開します。すべてのチーム間でのすべての API が即座に一元化され、検索できるようになります。
API を見つけて統合
開発者が新しい返金フローを構築するためのチケットを引き受ける場面を想像してください。返金の処理に使用する正しい API を見つける必要があることはわかっているものの、どこから始めるべきかわかりません。多くの企業では、開発者はどの API を使用すべきかについて Slack で質問し、地球の反対側にいる同僚から回答が来るまで何時間も待つことがあります。Compass を利用しているチームは、これらすべてをセルフサービスで行えます。開発者は API エンドポイントを検索し、必要な情報を Compass 内で数秒で正確に見つけられます。つまり、情報を探している開発者はより迅速に見つけられ、その API を所有するチームは中断されることが少なくなります。
API の変更に関する通知を受け取る
マイクロサービスの世界では、各サービスは自律的にデプロイされ、ときには利用者は変更を把握しておく必要があります。幸い、Compass は API ドキュメントの内容だけでなく、API が時間の経過とともにどのように変更されているかも把握しています。同僚が API ドキュメントを更新するプル リクエストをマージするたびに、Compass もドキュメントのバージョンを更新します。そのため、開発者が Compass で確認するバージョンは常に最新の API です。
過去の変更も変更ログ ページに表示されるため、過去の重要な変更の発生した日時を確認できます。
開発者は必要なドキュメントを入手してコードのリリースを加速
Postman による最近の API 開発者調査では、開発者の 52% が API での作業時の最大の問題は、ドキュメントが見つからないことだと回答しています。ドキュメントが見つからないと、開発が遅くなり、新しいエンジニアのオンボーディングがより困難になり、ソフトウェアの信頼性が低下します。
独自の社内 API カタログを作成する必要があるとしたら、巨大なプロジェクトになり、多くの不確定要素を伴っていたでしょう。その作業はすべて完了しています。一元化されたドキュメント ハブをすぐにご利用いただけます。
チームが必要とする情報を提供し、リリースが加速する様子をご覧ください。🚀