ApidogのスプリントブランチでAPIのイテレーションを効率化する方法は？

APIを反復し維持することは、製品開発において重要です。製品が新しい機能や調整で進化するにつれて、それに対応するAPIの更新や修正が必要になります。特にスピード感のある環境ではその影響が顕著です。

しかし、APIの反復は必ずしも簡単ではありません。製品のアップグレードや修正とともにAPIを管理することは、多くの課題を引き起こします：

• 既存のAPIの安定性を確保しながら、どのように効果的にAPIを反復し、テストすることができるでしょうか？
• 複数の並行開発の反復においてAPIをどのように管理し、干渉を防ぐことができるでしょうか？

これらのシナリオに対処するために、Apidog は「スプリントブランチ」機能を導入しています。この機能は、独立したブランチでAPIを管理できる柔軟な方法を提供し、オンラインAPIの安定性に影響を与えずに反復、アップグレード、新機能の開発を可能にします。

スプリントブランチ機能は、バージョン管理、並行コラボレーション、迅速なマージをサポートしています。各ブランチは独立したバージョンとなり、干渉を防ぎ、ブランチ内の変更は迅速にメインブランチにマージできます。

スプリントブランチのユースケースの理解

「スプリントブランチ」機能を使用すると、プロジェクト内に複数の開発ブランチを作成し、メインブランチ（すなわち現在の安定版）に影響を与えることなく、異なる段階でAPIをアップグレード、反復、テストできます。

スプリントブランチを使用する際の考慮事項：

• 機能の開発とテスト：新しいスプリントブランチで新機能を開発およびテストし、メインブランチの安定版に影響を与えないようにします。
• アップグレードとバグ修正：専用ブランチでAPIをアップグレード、更新、またはバグを修正し、成功したテストの後にメインブランチにマージします。
• 実験と検証：APIに実験的な修正を加え、それらの有効性を確認した後にメインブランチにマージするかどうか決定します。

スプリントブランチを使用しない場合：

• 小さなAPIの更新や簡単なバグ修正の場合は、メインブランチで直接操作する方が便利です。
• ビジネス要件として外部ユーザーに複数のAPIバージョンを提供する必要がある場合は、「APIバージョニング」機能を利用して、外部ユーザーに対して安定性と一貫性を確保することを推奨します。

以下は「スプリントブランチ」機能の簡単な紹介です。詳細な使用方法については、ヘルプ文書内のスプリントブランチモジュールを参照してください。始める前に、Apidogが最新バージョンに更新されていることを確認してください。

スプリントブランチの作成

プロジェクトの役割が「管理者」または「編集者」の場合は、ディレクトリツリーの右上隅にある「スプリントブランチ」コンポーネントの「新しいスプリントブランチ」オプションをクリックして、反復関連の作業を開始するための新しいスプリントブランチを作成できます。

スプリントブランチでのAPI設計

Apidogのスプリントブランチ機能は、反復中に修正されたり新たに追加されたコンテンツのみを対象としています。そのため、新しいスプリントブランチは最初は空であり、修正または追加するコンテンツを選択する必要があります。

インポートされたリソース（API、APIユースケース、データモデルを含む）には、メインブランチとの明確な関連識別子があります。スプリントブランチ内で新たに作成されたリソースには関連識別子はありません。

API設計プロセス中に、特定のスプリントブランチリソースをメインブランチと比較して、そのリソースとメインブランチとの違いを確認することもできます。

スプリントブランチでのAPIテスト

「テスト」機能はスプリントブランチでもサポートされています。「新しいテストシナリオ」を新たに作成するか、メインブランチから既存のテストシナリオをインポートすることができます。

ディレクトリツリー内でインポートされたテストシナリオは、メインブランチのリソースに対して明確な関連識別子を持っています。これは「API」のリソース識別子と同様です。

スプリントブランチ内でもメインブランチと同様にテストシナリオをオーケストレーションできます。テストシナリオには、スプリントブランチとメインブランチのAPIが含まれる場合がありますので、システムは「ブランチアイコン」を利用して、各テストステップでどのリソース（スプリントブランチまたはメインブランチ）が使用されているかを区別します。

これらのステップの詳細を表示することで、それらに関連するリソースがどのブランチに属しているかを確認できます。

関連するAPIとテストシナリオを設計しオーケストレーションした後、テストを実施できます。

システムは、ステップで識別されたリソースソースに基づいて、対応するデータを使用して自動テストを行います。テストステップがスプリントブランチのリソースを使用すると識別された場合、そのテストはスプリントブランチのデータを使用します。一方で、メインブランチのリソースを使用すると識別された場合、そのテストはメインブランチのデータを使用します。

スプリントブランチのマージ

スプリントブランチでAPI開発を完了し、成功裏にデプロイした後、これらの変更をメインブランチにマージできます。マージされた内容は、一部またはすべてのAPIに変更されることがあります。

マージエントリは、ディレクトリツリーの右上隅にある「ブランチコンポーネントドロップダウンメニュー」にあります。また、APIのディレクトリツリー下に「メインブランチにマージ」ボタンが表示されます。

APIの「メインにマージ」ボタンをクリックすると、マージの概要ポップアップが表示されます。このポップアップでは、現在のスプリントブランチとメインブランチの間で変更されたリソースを表示できます。また、マージ後にメインブランチでリソースの状態をどう調整するか（例：「開発中」、「テスト中」、「公開済み」など）を選択することもできます。

ディレクトリツリーでリソースをクリックすると、その詳細内容が拡張表示され、マージするかどうかを判断するのに役立ちます。異なるリソースタイプには異なるマージロジックがあります。

マージ後、メインブランチで変更されたリソースが表示される通知が出ます。

メインブランチでのマージの表示と取り消し

メインブランチの「API」内では、リソースの履歴を確認することで最近のマージ操作によってもたらされた変更を確認できます。マージ元のブランチも確認できます。

特定の変更内容を表示し、他のバージョンと比較することができます。この履歴機能により、変更履歴を追跡し、必要に応じてコンテンツをロールバックできます。

ブランチのアーカイブ、復元、削除

ブランチをマージした後、「設定」->「スプリントブランチ」を通じてスプリントブランチ管理ページにアクセスできます。この管理ページでは、プロジェクト内のすべてのスプリントブランチとその統計情報を表示できます。これらのブランチに対してアーカイブ、復元、および反復ブランチの削除など、さまざまな操作を行うこともできます。

ApidogにおけるスプリントブランチのFAQ

1 スプリントブランチ機能ではすべての種類のAPIがサポートされていますか？

現時点では、HTTP APIのみがサポートされています。

2. 誰が反復ブランチを作成できますか？

プロジェクトの管理者および編集者です。

3. 誰が反復ブランチにアクセスできますか？

プロジェクトの管理者、編集者、および読み取り専用メンバーです。

4. 誰が反復ブランチからの変更をマージできますか？

プロジェクトの管理者および編集者です。

5. 反復ブランチを別の反復ブランチにマージできますか？

現在はサポートされていません。メインブランチへのマージのみがサポートされています。

6. 反復ブランチで作業中にメインブランチのAPIも変更された場合、マージ後に何が起こりますか？

マージ後、反復ブランチの変更がメインブランチの同じAPIに対する変更を上書きします。つまり、メインブランチのAPIへの追加、削除、または修正が、反復ブランチのコンテンツによって置き換えられます。

7. メインブランチから反復ブランチに最新の更新をプルする方法はありますか？

この機能は開発中で、近日中に利用可能になる予定です。

8. 反復ブランチでリソースがいくつか削除された場合、マージ時にメインブランチにどのような影響がありますか？

APIやデータモデルなどの全リソースが削除された場合、これらのリソースはもはやメインブランチと関連付けられなくなります。したがって、メインブランチの対応するリソースにはマージ時に影響がありません。これは変更がないのと同等です。

これは、スプリントブランチの基本的な原則がリソースの修正および追加のみを含むためです。削除操作はメインブランチで直接実行する必要があり、スプリントブランチでは削除操作は処理されません。

スプリントブランチ内のAPIまたはデータモデルリソースがメインブランチと関連付けられており、そのリソースの一部（パラメーターや説明など）を削除すると、マージ後にメインブランチの対応するリソースも削除されます。この操作は、反復ブランチ内のリソースを修正することに相当します。

9. メインブランチのAPIと同じURLおよびパラメーターを持つ新しいAPIが反復ブランチ内で作成された場合、マージ後に何が起こりますか？

スプリントブランチで新しく作成されたAPIはメインブランチのAPIと同じURLとパラメーターを持ちますが、デフォルトでは関連付けられません。マージされると、メインブランチにはスプリントブランチと全く同じ新しいAPIが追加されます。例えメインブランチに同じURLとパラメーターを持つAPIがすでに存在してもです。

したがって、既存のAPIをアップグレード、テスト、または修正したい場合は、メインブランチからAPIをインポートして関連付けを確保してください。これにより、APIが変更された場合、メインブランチのAPIもマージ後に同期して更新されます。

10. 以前のスプリントブランチのコンテンツに戻して復元できますか？

はい。

何らかの理由で以前の反復コンテンツを表示する必要がある場合、アーカイブされた状態から通常のブランチ状態に復元できます（スプリントブランチの制限に注意）。

復元後、APIのディレクトリツリーにあるブランチに再度アクセスできます。アーカイブ前のブランチのデータは、自動的に変更なしで保持されます。ブランチ履歴のコンテンツを復元したい場合、このブランチを使用して再度メインブランチにマージして復元を完了できます。

リソース個別については、「API」内での「履歴」機能を直接利用してロールバックと復元を行うことを推奨します。

11. スプリントブランチのAPIドキュメントを他の人と共有できますか？

内部のコラボレーションや共有のために、プロジェクトに参加しているメンバーと「コラボレーションリンクをコピーする」ことができます。現在、APIドキュメントの外部共有はサポートされていません。

結論

Apidogの「スプリントブランチ」機能は、API設計とテストプロセスを最適化します。独立したブランチを作成することにより、チームは新機能を開発し、バグを修正し、メインブランチに干渉することなく実験することができます。