アジャイルAPI-可能ですか？

多くの記事や本は、APIを適切に設計する方法に専念していますが、絶えず変化する（柔軟な）APIのトピックに触れた人はほとんどいません。 動的に開発している会社は、多くの場合、週に数回、場合によっては1日にリリースします。 ただし、新しい機能を追加するには、既存のAPIを常に変更する必要があります。 この記事では、Badooでこの問題をどのように解決するか、作業でどのようなアプローチとアイデアを使用するかについて説明します。

まず、Badooについてもう少し話をして、APIを使用するユーザーと、なぜ頻繁に変更されるのかを理解する必要があります。

内部APIとその使用

Badoo API（メッセージングプロトコル）は、クライアントとサーバー間で交換されるデータ構造（メッセージ）と値（列挙）のセットです。 プロトコル構造は、 Google protobuf定義に基づいて設定され、別のgitリポジトリに保存されます。 これらの定義に基づいて、さまざまなプラットフォームのモデルクラスが生成されます。

サーバーと5つのクライアント（Android、iOS、Windows Phone、モバイルWeb、デスクトップWeb）の6つのプラットフォームで使用されます。 さらに、各プラットフォームのいくつかのスタンドアロンアプリケーションで同じAPIが使用されます。 これらすべてのアプリケーションとサーバーが必要な情報を交換できるように、私たちのAPIは十分に大きくなっています。 いくつかの数字：

• 450投稿、2665フィールド。
• 135 enum'ov、2096値。
• サーバー側で制御できる125個の機能フラグ。
• クライアント動作の機能とクライアントがサポートするプロトコルをサーバーに伝えるクライアント動作の165フラグ。

いつこれを行う必要がありますか？ 昨日！

Badooでは、可能な限り迅速に新機能を実装するよう努めています。 ロジックは単純です。新しい機能を備えたバージョンがすぐに表示されるほど、ユーザーはそれらをより速く使用できます。 さらに、A / Bテストを並行して実施しますが、この記事では詳しく説明しません。

機能の実装時間（アイデアからリリースまで）は、要件の記述、APIと技術文書の変更、新しいバージョンの実装とリリースを含む、わずか1週間の場合があります。 平均して、すべてに約1か月かかります。 ただし、これは、アプリケーションごとに月に1つの機能を追加することを意味するものではありません。 私たちは多くの新機能に並行して取り組んでいます。

そのような偉業を成し遂げるためには、適切な速度で移動できるプロセスを開発する必要がありました。

どちらの側にアプローチしますか？

たとえば、製品の所有者は新しいアイデアを提供し、API開発者にプロトコルを拡張してクライアント側に新しい機能を実装するように依頼します。
まず、多くの人々が新しい機能の実装に取り​​組んでいることを理解する必要があります。

• プロダクトオーナー;
• デザイナー
• サーバーソリューション開発者。
• API開発者
• さまざまなプラットフォームのクライアントアプリケーション開発者。
• QA;
• データ分析。

全員がお互いを理解し、同じ言語を話すことをどのように保証できますか？ 機能要件（ PRD ）を説明する文書が必要です。通常、このような文書は製品所有者が作成します。 彼は、要件、ユースケース、フローの説明、デザインスケッチなどのリストを含むWikiページを作成します。

PRDに基づいて、APIに必要な変更の計画と実装を開始できます。

ここでも、すべてがそれほど単純ではありません。

プロトコル設計アプローチ

サーバーとクライアント間の「責任の分散」には多くのアプローチがあります。 アプローチの範囲は、「すべてのロジックがサーバーに実装されている」から「すべてのロジックがクライアントに実装されている」までです。 各アプローチの長所と短所について説明します。

オプション1。すべてのロジックがサーバーに実装されます（クライアントはMVCテンプレートからのビューとして機能します）。

長所：

• すべてのプラットフォームの新しい機能は、サーバー上で一度だけ実装するのに十分です。
• 更新できるのはサーバーロジックとトークンのみです。クライアントアプリケーションに変更を加えて新しいリリースを準備する必要はありません（ネイティブアプリケーションに関しては非常に大きなプラスです）。

短所：

• より複雑なプロトコル（多くの場合、機能にはクライアントに簡単に実装できるいくつかの順次アクションが必要であり、これらの手順をプロトコルに追加するとすべてが非常に複雑になります）。
• クライアントアプリケーションごとに動作が異なる場合は、クライアントアプリケーションごとに、およびアプリケーションのサポートされているバージョンごとに、サーバー上に個別の機能実装を用意する必要があります。
• 低速または不安定な接続を介して、アプリケーションのユーザビリティに悪影響を与える可能性があります。
• ビジネスロジックがサーバー側で実装されている場合、サーバーへの接続がない場合、一部の機能は実装が非常に困難または不可能にさえなります。

オプション2。すべてのロジックはクライアントに実装されます-クライアントアプリケーションはすべてのロジックを含み、サーバーをデータソースとして使用します（ほとんどのパブリックAPIで一般的）。

長所：

• サーバー要求の数が少ないため、ユーザーは応答を待つ必要が少なくなります。
• オフラインでも、低速または不安定なネットワークでも動作します。
• キャッシングは大幅に簡素化されています。
• 必要に応じて、プラットフォームやクライアントのバージョンごとに異なる動作を実装する方がはるかに簡単です。
• サーバーとのより簡単な対話-チームはお互いを見ずに作業できます。

短所：

• もっと時間がかかります。 すべてのロジックは、サーバーではなく、各クライアントで実装する必要があります。
• 最も小さな変更でも実装するには、各クライアントアプリケーションをリリースする必要があります。
• 各アプリケーションにはロジックの個別の実装があるため、コードでエラーが発生する可能性が高くなります。

一方では、最初のアプローチでは、サーバーにビジネスロジックを1回だけ実装し、それをすべてのクライアントで使用できます。 一方、異なるプラットフォームは、独自の特性、トークンの独自の構造、異なる機能セットによって特徴付けられ、機能自体は異なる時間に実装されることがよくあります。 ほとんどの場合、プロトコルをよりデータ指向にすると、クライアントアプリケーションがある程度自由になり、独自の方法で動作できるようになります。 しかし、いつものように、単一の正しいソリューションはないため、これら2つのアプローチの間で絶えずバランスを取っています。

技術文書

数年前、当社が小規模だったとき、プロトコルを使用したクライアントは2つ（AndroidとiOS）だけでした。 開発者はほとんどいなかったので、すべての作業時間について口頭で話し合ったため、プロトコルのドキュメントには、protobuf定義のコメントに一般的なロジックの説明しか含まれていませんでした。 通常、次のようになりました。



その後、さらに3つのクライアントプラットフォームが登場しました。WindowsPhone、モバイルWeb、デスクトップWeb、およびAndroidおよびiOSチームの開発者の数は3倍に増加しました。 口頭での議論はより高価になり、すべてを注意深く文書化する時が来たと判断しました。 現在、このドキュメントには、フィールドコメントだけではありません。 たとえば、機能、シーケンス図、スクリーンショット、サンプルメッセージの簡単な説明を追加します。 最も単純な場合、ドキュメントは次のようになります。



6つのプラットフォームすべてのアプリケーションおよびQA開発者は、このドキュメントとPRDを主要な知識源として使用します。

このドキュメントは、新しい関数の実装だけでなく、既に実装されている機能がどのように機能するかを知る必要がある場合に、アプリケーションの大幅な再設計とリファクタリングにも役立ちます。

RTFM開発者に簡単に伝えることができるようになり、時間を大幅に節約できます。 さらに、このアプローチは、初心者がすべてがどのように機能するかを理解し、開発プロセスにすばやく関与するのに役立ちます。

提供ドキュメント

reStructuredText形式の技術文書を準備し、プロトコル定義とともにgitリポジトリに保存し、 Sphinxを使用して、社内ネットワークの会社の従業員が利用できるHTMLバージョンを生成します。

ドキュメントは、プロトコルの実装のさまざまな側面やその他の問題に焦点を当てたいくつかの主要なセクションに分かれています。

• プロトコル -protobuf定義のコメントに基づくドキュメント。 製品機能-機能の実装に関する技術文書。 （コンベヤー図など）。
• 一般 -製品の機能に固有ではないプロトコルおよびフロードキュメント。
• アプリケーション機能 -いくつかの異なるアプリケーションがあるため、このセクションではそれらの違いについて説明します。 前述のように、プロトコルは共有されます。
• 統計 -アプリケーションのパフォーマンスに関する統計と情報の収集に関連するプロトコルとプロセスの一般的な説明。
• 通知 -ユーザーが受け取る可能性のあるさまざまな種類の通知のドキュメント。
• アーキテクチャとインフラストラクチャ -プロトコルの低レベル構造、バイナリプロトコル形式、A / Bテストのフレームワークなど。

そのため、APIに変更を加えました。 次は？

PRDに基づいてプロトコルとドキュメントに変更を加えた後、PRDとAPIの両方がレビューの2つの段階を経ます。 まず、プロトコルを担当するチーム内で、次にこの機能が実装されるプラットフォームのアプリケーション開発者向けです。

この段階で、次の問題に関するフィードバックを受け取ります。

• 十分性-各プラットフォームに機能を実装するのに十分なAPIの変更があります。
• 互換性-変更がプラットフォーム上のアプリケーションコードと互換性があるかどうか。 プロトコルを少し修正して、1つまたは2つのプラットフォームで多くの時間とリソースを節約できるかもしれません。
• クリア

すべての変更について話し合って承認した後、サーバーチームとクライアントチームは機能の実装に進むことができます。

この段階で仕上げるのは良いことです。 多くの場合、ProductOwnerはこの機能を改善する計画を既に持っていますが、現在の形式でアプリケーションをリリースしたいと考えています。 またはさらに興味深い。 あるプラットフォームに対して変更を行うように求められることがありますが、残りのプラットフォームについてはすべてをそのままにしておきます。

子供としての特徴、それは成長し、発達します

機能が開発中です。 A / Bテストを実施し、新機能のリリース後にフィードバックを分析します。 分析により、機能を改善する必要があることが示される場合があります。 次に、製品所有者がPRDを変更します。 そして、「問題」が発生します。 現在、PRDはプロトコルおよびドキュメント形式に準拠していません。 さらに、あるプラットフォームでは既に変更が行われており、他のチームはまだ始まったばかりである可能性があります。 起こりうる競合を防ぐために、PRDバージョン管理を使用します。 たとえば、あるプラットフォームでは、バージョンR3に従って機能を実装できます。 しばらくして、プロダクトオーナーは新しい機能を改良し、PRDをバージョンR5に更新することにしました。 そして、PRDの新しいバージョンを反映するために、プロトコルと技術文書を更新する必要があります。

PRDの更新を監視するには、 Confluence （Atlassian wiki）の変更履歴を使用します。 プロトコルの技術文書では、WikiページのアドレスにPageVersion = 3を指定するか、変更履歴からリンクを取得するだけで、PRDの特定のバージョンへのリンクを追加します。 これにより、各開発者は特定の機能が実装されているPRDのバージョンまたは部分に基づいて常に認識しています。

PRDのすべての変更は、新しい機能と見なされます。 製品所有者は、変更を開発に送信するときが来るまで、変更（R1、R2 ...）を蓄積します。 彼らは、プロトコルの必要な変更を記述するAPI開発者向けのタスクを準備し、その後、異なるプラットフォームを担当するすべての開発チームが同じタスクを受け取ります。 次の一連の変更が機能の準備ができると、別のチケットが作成されてAPIが完成し、すべてのプラットフォームの変更が同じ方法で実装されます。



PRDの変更リストを受け取ったら、このプロセスの最初に戻ります。つまり、プロトコルなどに変更を加えます。 もちろん、これは私たちの生活を複雑にします。R3バージョンに基づく以前に実装された機能とクライアントアプリケーションをサポートする必要性を誰もキャンセルしていないためです。 この問題を解決するには、いくつかのプロトコル変更管理ツールを使用します。

プロトコル変更管理

前のセクションでは、PRDバージョン管理について説明しました。 APIでこれらの変更を実装するには、プロトコルバージョン管理のオプションを検討する必要があります。 簡単にするために、長所と短所がある3つのオプション（レベル）があると言えます。

プロトコルレベル

このアプローチは、ゆっくりと変化するパブリックAPIに広く使用されています。 プロトコルの新しいバージョンが出てきたら、すべてのクライアントは古いバージョンの代わりに使用を開始する必要があります。 一連の機能があり、プラットフォームによって実装時間が非常に異なるため、このオプションは使用できません。 たとえば、プロトコルにはいくつかのバージョンがあります。

• V1。 機能A、B、Cをサポートします。
• V2。 関数B '、C、およびDをサポートします。ここで、B'はBの更新された関数です（異なるコマンドシーケンスが必要です）。

したがって、アプリケーションに機能Dを実装する必要がある場合は、機能BをバージョンBにアップグレードする必要がありますが、現在は必要ありません。

Badooでは、このアプローチでバージョン管理を行ったことはありません。 この場合、次の2つのオプションの方が適しています。

メッセージベースのバージョン管理

このアプローチでは、関数に変更を加えた後、新しいフィールドセットで新しいメッセージが作成されます（protobufのデータ構造）。 要件が大幅に変更された場合、このアプローチはうまく機能します。

たとえば、Badooでは、各ユーザーがアルバムを持っています。 以前は、ユーザーは独自のアルバムを作成して写真を入れることができました。

AddPhotoToAlbumV1 {
required string album_id = 1;
required string photo_id = 2;
}


次に、プロダクトオーナーは、3種類の事前定義済みのアルバムで十分だと判断しました。私の写真（私の写真）、他の写真（他の写真）、プライベート写真（個人写真）です。 クライアントがこれらの3つのタイプを区別するには、enumを追加する必要がありました。 したがって、メッセージの次のバージョンは次のようになります。

AddPhotoToAlbumV2 {
required AlbumType album_type = 1;
required string photo_id = 2;
}


このアプローチは正当化される場合もありますが、注意する必要があります。 変更がすべてのプラットフォームですぐに実装されない場合、古いバージョンと新しいバージョンの両方をサポートする（新しい変更を追加する）必要があります。つまり、混乱が増大します。

フィールド/値レベル

可能な限り、同じメッセージまたは列挙を使用して、いくつかのフィールド/値を削除するか、新しいフィールド/値を追加します。 これはおそらく、私たちの実践で最も一般的なアプローチです。

例：

AddPhotoToAlbum {
optional string album_id = 1 [deprecated=true];
optional string photo_id = 2;
optional AlbumType album_type = 3;
}


この場合、クライアントアプリケーションは引き続き古いメッセージを使用し、新しいバージョンのアプリケーションはalbum_idの代わりにalbum_typeを使用できます。

ところで、常にオプションのフィールドを使用します。 これにより、必要に応じてフィールドを削除できます（Google開発者は同じ結論に達しました ）。

プロトコル変更サポート

前述のように、APIはサーバーと5つのクライアントプラットフォームで使用されます。 クライアントアプリケーションの新しいバージョンは毎週リリースされます（1か月あたり約20のバージョンのアプリケーションがあり、動作が異なり、プロトコルのさまざまな部分を使用できます）。したがって、アプリケーションの新しいバージョンごとにプロトコルの新しいバージョンを作成することはできません。 プロトコルのバージョン管理に対するこのアプローチでは、サーバーが何千もの異なるアプリケーションの組み合わせをサポートする必要があります。 このソリューションは理想とはほど遠いものです。

そのため、各アプリケーションがサポートするプロトコルバージョンに関する情報をサーバーに即座に送信するオプションを決定しました。 この場合、サーバーは、アプリケーション自体が提供するサポートされている機能のリストに依存するだけで、任意のクライアントアプリケーションと対話できます。

たとえば、最近「新機能」機能を実装しました。 したがって、アプリケーションの新機能についてユーザーに通知します。 この機能をサポートするアプリケーションは、SUPPORTS_WHATS_NEWフラグをサーバーに送信します。 その結果、サーバーは、クライアントに新しい機能に関するメッセージを送信でき、それらが正常に表示されることを認識しています。

APIで順序を維持する方法は？

これがパブリックAPIである場合、通常は特定の日付が決定され、その後、古い部分が機能しなくなります。 Badooの場合、これはほとんど不可能です。古い機能のサポートを削除するよりも、新しい機能を実装する方が重要だからです。 このような状況では、3段階の手順に従います。

最初の段階では、プロトコルの一部を削除することを最終的に決定するとすぐに「廃止」とマークされ、すべてのクライアントプラットフォームのアプリケーション開発者が対応するコードを削除するタスクを受け取ります。

第2段階では、プロトコルの古い部分をすべてのクライアントのコードから削除する必要がありますが、サーバー上のこのコードを長時間削除することはできません。すべてのユーザーがアプリケーションをすばやく更新するわけではありません。

最後の段階で、廃止されたコードがすべてのクライアントアプリケーションから削除され、プロトコルのこの部分を使用するバージョンが使用されなくなった場合、サーバーコードおよびAPIから削除できます。

コミュニケーション

この記事では、借用または作成したいくつかの技術的および組織的アプローチについて説明しました。 ただし、コミュニケーションの問題については一切触れませんでした。 しかし、コミュニケーションは私たちの仕事の80％です。 多くの場合、この機能がプロトコルレベルでどのように実装されるかを理解する前に、多くの人々と機能自体および可能な実装パスについて議論する必要があります。

成功するプロジェクトの基礎は、適切に調整されたチームの努力です。 幸いなことに、ほとんどの開発者は、標準化なしでさまざまなプラットフォームのソリューションを使用することがいかに難しいかをよく知っているため、私たちをサポートしています。

十分に文書化されたAPIは、開発者ではない人々がAPI自体とその開発プロセスを理解するのにも役立つことを認識しました。 テスターはテスト中にドキュメントを参照し、プロダクトオーナーはそれを使用して、プロトコルの変更を最小限に抑えてタスクのソリューションを考え出します（そう、すばらしいプロダクトオーナーがいます！）。

おわりに

柔軟なAPIと関連プロセスを開発するときは、忍耐強く実用的である必要があります。 プロトコルとプロセスは、コマンド、ソフトウェアとプラットフォームのバージョン、アプリケーションの古いバージョンのさまざまな組み合わせで動作し、他の多くの要因も考慮する必要があります。 それでも、これは非常に興味深いタスクであり、現時点ではほとんど情報が公開されていません。 したがって、この分野でのベストプラクティスを共有できたことを非常に嬉しく思います。 ご清聴ありがとうございました！