最近、15年の歴史を持つ支払いサービスであるYandex.Kassi APIを再起動しました。 このような野心的な課題を解決する方法をお伝えしたいと思います。 この資料は一連の記事にまとめられているため、ここでは、APIの設計、処理、およびツールとプロセスについて詳しく説明します。

ユーティリティを評価するためのキーワード： API、REST、OpenAPI、Swagger、システム相互作用のリファクタリング 。

問題文、またはこの会話は何についてですか

小規模なチームが新興企業から大企業に転向するとき、ソフトウェアコンポーネントとその相互作用に関するすべての知識を心に留めることはできません。 したがって、2つの困難があります。

• 部門ごとに独自の計画があり、同時に作業を行うことが常に可能であるとは限りません。 相互作用の手順に同意し、海岸で文書化する必要があります。
• サービス操作のルールおよびそれとの統合に関する参照知識を維持することが重要です。 当事者間の相互作用の順序を修正しない場合、これははるかに困難です。

スクラムなどの開発方法論により、これらの問題を短時間で除去できます。

• 一部のタスクの複雑さは1つのチームの範囲を超えており、一緒に対処する必要があります。
• 1つの製品のみに明確に帰属することのできないタスクがあり、システムのいくつかのコンポーネントの調整された変更が必要です。
• メンテナンスタスクには、古いサービスの改良が必要です。 非常に古いため、それらの知識は以前の明るさを失いました。

10年間、Yandex.Moneyの開発者は、WikiページからXMLスキーマ、JSONスキーマ、OpenAPI / Swaggerまでの相互作用を記述することで、これを確信してきました。

API仕様設計ツール-最初は言葉でした

すべては、リクエストとレスポンスの例とともに、WikiとMicrosoft Wordでのサービスの相互作用の説明から始まりました。 原則として、データ転送にはXMLが使用されました。 これは何もないよりはましでしたが、そのような文書化の方法は、人から人へ知識を移すのに適しています。

任意のテキスト記述は、異なる部門の人々によって曖昧に解釈される可能性があるため、概念と用語の統一されたシステムが必要でした。 開発者の数が増えるにつれて、相互作用の記述の形式化が必要になりました。

操作、データ型、およびそれらの境界条件の正式な説明は、開発だけでなく、ユニットテストの自動化にも必要です。 最初の正式なAPIサービスコントラクトをXMLスキーマ形式で説明し、後でJSONスキーマを試しました。 ただし、どちらも完全ではないため、WikiまたはMicrosoft Wordのテキスト記述から完全に切り替えることは困難です。

• XMLスキーマでは、作業シナリオを説明する完全なドキュメントを追加することは不可能であり、個別に保持する必要があります。
• JSONスキーマ-十分なインストルメントサポートのない粗すぎる仕様でも、完全なドキュメントを含めることができません。

以前はSwaggerとして知られていたOpenAPIが理想的でした。 OpenAPI Initiativeは、Linux Foundationが運営するオープンソースプロジェクトです。 彼には素晴らしい未来が待っていると確信しています。

OpenAPI 3では、ドキュメントと対話形式の説明を1つの仕様ファイルにまとめることができます。 これは非常に重要な品質です。テキストドキュメントとAPI仕様ファイルが同期していないことはありません。

私たちのプロジェクトでは、YAML形式のOpenAPI 3仕様ファイルを使用しています。その理由は次のとおりです。

• JSONよりもYAMLの方が読みやすいです。
• CommonMark形式（以前のMarkdown）のドキュメントが含まれています。 これらは、フォーマット、リスト、テーブル、引用、コード例です。
• ドキュメントは、目的の仕様オブジェクトに追加され、個別のセクションに記述されていません。

サービス分解および変更管理

多くの組織が直面する一般的な問題は、ドキュメント変更管理です。 並行して、プロジェクトごとに別々の変更が加えられた多くのドキュメントがあります。 多くのプロジェクトのドキュメントを維持することは非常に難しいため、人為的エラーの可能性が高くなります。

OpenAPI仕様はYAML形式のテキストファイルです。つまり、コードと同様に作業できます。

• バージョン管理システムを使用します。
• ブランチ、タグ、リリースに基づいて変更を柔軟に管理します。
• 並行して、多くの人々が多くのプロジェクトに変更を加えます。
• レビュー手順を作成し、メイン文書への変更を受け入れます。
• 特定のプロジェクトのコンテキストでドキュメントの特定のバージョンを参照します。

私たちのプロジェクトは、 Webページプラグインを備えたAtlassian Bitbucketバージョン管理システムを使用しています。 これにより、コードと同様に仕様を同時に操作し、HTML形式で組み立てられたドキュメントを表示できます。

主要なタスクを一連のサービスに分解する場合、技術コミュニティではなく、アプリケーション領域のドメインごとに機能を分割するという原則に依存することをお勧めします。

各APIサービスの背後には特定のビジネスプロセスがあり、各APIサービスは個別のOpenAPI仕様ファイルによって記述されます。 そして、彼自身の製品チームがそれを担当しています。 これを念頭に置いて、OpenAPI仕様ファイルセットでは、各ファイルはそのアプリケーション製品に対応しています。

したがって、残りは技術的な問題でした。Bitbucketで適切なリポジトリを作成し、各APIサービスを担当するレビューアのグループを構成することは残っています。 その結果、BitbucketにはAPIの共通カタログであるAPI仕様のプロジェクトがあります。

仕様ファイルは、対象製品ごとにグループ化されています。

• 単一の製品のAPI仕様は、単一のリポジトリでホストされます。
• さまざまな製品のAPIがさまざまなリポジトリでホストされています。

つまり、1つのリポジトリが1つの製品に対応します。製品ビジネスプロセスとそのAPI仕様の開発と保守のプロセスを担当するチームです。

完了した多くのプロジェクトの結果によると、Gitリポジトリの構造は次のとおりでした。

• マスターブランチは、現在の仕様の状態を反映します。これは、事実上戦闘システムにあり、使用可能です。
• プロトタイプブランチは、一連の製品使用シナリオを作成するためのアウトラインデザインを対象としています。 将来的には、その後の技術的解決策の基礎を形成した初期構造の回顧に役立つ可能性があります。
• 設計タスクは機能ブランチで開発されます。 1つの機能ブランチは、APIを変更するための単一のプロジェクトまたはタスクです。
• プロジェクトには、 Swagger-UI初期化設定を含むindex.htmlファイルが含まれています。 Webページプラグインのおかげで、ドキュメントをHTMLとして表示できます。 したがって、リポジトリの各ブランチはオンラインでHTMLドキュメントを表示し、外部システムおよびドキュメントから参照できます。

構造に加えて、リポジトリを操作するためのルールを開発する必要がありました。

• マスターブランチとプロトタイプブランチへの書き込み権限はありません;直接記録は禁止されています。 すべての仕様変更は、機能ブランチからのプルリクエストとして行われます。
• Pull-Requestからの変更が主要な仕様に該当する場合、このPull-Requestは、必要なすべてのレビュー担当者および任意の数のオプションのレビュー担当者から承認を受ける必要があります。
• 履歴が仕様を変更するタスクの履歴であるプルリクエストは、変更について議論し、同意するのに最適です。
• Pull-Requestの存在のどの段階でも機能ブランチに変更を加えることができますが、新しい変更にはレビューアとの調整が必要です。
• マスターブランチへのPull-Requestのマージは、作業中のリリースが戦闘操作に投入されたときに実行されます。

これらの原則のおかげで、仕様を操作するための便利で透過的で予測可能な環境が得られました。

問題に対する高品質のソリューションの基礎としての設計優先アプローチ

新しいサービスを設計するとき、 RESTの原則に依存しますが、それらに完全には準拠しません-たとえば、これがサービスのアーキテクチャを複雑にしたり、常識に反する場合。

RESTの価値は、このアプローチでは、サービスを一連のエンティティとそれらのアクションに分解する必要があることです。

RESTは、 ドメイン駆動設計の便利な反映です。 私の意見では、RESTアーキテクチャのおかげで、RPCアプローチを使用して以前に行ったものと比較すると、適用されたタスクのよりシンプルで高品質のオブジェクトモデルが得られます。

高品質の製品を作成するために、開発者は以前のプロジェクトの経験のコンテキスト外でタスクの主題領域を注意深く研究する必要があります。 したがって、デザインファーストは、適用された問題を解決するアプローチとしての地位を確立しています。 次の2つの段階に分けることができます。

1. 研究、説明、および対象分野のエンティティとプロセスの形式化。

   
   
   
   
   
   
   
2. 他のサービスとの可能な接続を考慮に入れて、APIサービスを使用するシナリオの形式化。 内部の専門用語ではなくドメイン用語を使用してください-この方法により、ユーザーによるサービスの操作の誤解を避けることができます。

この作業の結果は、APIサービスの仕様になります。

• ドメインエンティティとその属性のセットを定義します。
• 各エンティティのライフサイクルと一連の状態を定義します。
• 各エンティティと考えられるエラー状況で一連のアクションを定義します

API仕様が既存の実装から生成される場合、コードファーストアプローチはお勧めしません。常に以前のプロジェクトからソリューションを継承し、問題を解決しません。 鶏と卵のパラドックスを解決する既知の方法はありません-質の高い実装を作成するには、まず対象分野を調査し、サービスを設計する必要があります。問題と設計の研究が実行される前に必要な実装を作成することはできません。

アンチパターンREST

「 RESTは新しいSOAPです 」という記事に触発されて、 RESTの誤った使用の例のトピックに関する実用的な考慮事項を共有したいと思います。

RESTはCRUDだけではありません

ワークショップで同僚がすべてのプロセスをCreate-Read-Update-Deleteモデルにパックしようと努力しているのは驚くべきことです。 人生はより複雑で豊かです。ビジネスプロセスは多くの操作で構成され、エンティティは多くの状態とそれらの間の遷移を持つことができます。

RESTの多くの記事では、Roy Thomas Fieldingの研究「 アーキテクチャースタイルとネットワークベースのソフトウェアアーキテクチャの設計 」をRESTを定義するための主要なソースとして挙げています（このペーパーの5章と6章を参照）。 http動詞GET-POST-PUT-DELETEを使用して、そこにない操作を定義する唯一の方法として使用することをお勧めします。

RESTは、サービスを一連のリソースとそれらの操作に分解する原則です。 POSTリクエストのみに基づいて必要な機能をすべて実装すると、これもRESTになります。

HTTPステータスのビジネスロジックエラーを反映する

HTTPプロトコルには、リクエストとレスポンスでデータを配信するためのトランスポート機能があることに注意してください。 ビジネスロジックとデータ転送レイヤーを混在させないでください。 「httpリクエスト」と「ビジネスプロセスアクション」の概念を明確に分離します。 HTTPステータスコードは、HTTPリクエストの実行ステータスを反映するためのものであり、ビジネスロジックレベルのタスクには使用しないでください。

ただし、多くの場合、付随するHTTPプロトコルを使用します。これにより、応答形式に次のような義務が課されます。

• OAuth 2.0認可フレームワーク
• OAuth 2.0認証フレームワーク：ベアラートークンの使用

HTTPステータスを使用することが適切な典型的な状況を次に示します。

1. 400：無効なリクエスト形式、リクエスト引数形式。
2. 401：クライアント認証なし。
3. 403：クライアント認証が不十分です。
4. 5xx：リクエスト、サービス、または中間ゲートウェイを利用できない技術的なエラー。

ビジネスロジックレベルの障害は、このHTTP要求によって操作が実行されたエンティティの属性として反映される必要があります。

たとえば、支払いの拒否は、クライアントのアカウントの資金不足が原因である可能性があります。 この場合、支払いのためのすべてのhttpリクエストは正常に完了します。 この状況は、エンティティ「支払い」の状態の属性の形式に反映される必要があります。

ビジネスロジック操作のためのPUT / PATCHクエリの使用

PUTリクエストは、サーバー上のドキュメントを同じタイプと構造の新しいドキュメントに置き換えることを目的としているため、ビジネスロジック操作に常に適しているとは限りません。 同じリソースへのGETリクエストは、PUTリクエスト引数を返す必要があります。

標準では、PUT要求を次のように定義しています。

PUTメソッドは、ターゲットリソースの状態を作成するか、要求メッセージペイロードに含まれる表現で定義された状態に置き換えることを要求します。



RFC 7231秒4.3.4

PUT要求の正しいアプリケーションの例は、 Yandex.Diskにファイルをアップロードすることです 。

RFC 5789 PATCHリクエストの適用性も制限されています。そのセマンティクスはPUTに似ており、リクエストの本文はRFC 6902 JSONパッチドキュメントであり、ドキュメントではありません。

JSONパッチドキュメントの例：

[ { "op": "remove", "path": "/a/b/c" }, { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }, { "op": "replace", "path": "/a/b/c", "value": 42 }, { "op": "move", "from": "/a/b/c", "path": "/a/b/d" } ]
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

この構文を使用してビジネスロジック操作をシンプルでアクセス可能な方法で記述することは容易ではないことに同意します。

したがって、タスクが上記の要件を満たしている場合はPUT / PATCHを使用し、そうでない場合はPOSTを使用することをお勧めします。

結論にいくつかの言葉

ITシステムは常に進化し、より複雑になっています。 おそらく今日の主な課題は、システムの複雑さの増大を制限することです。 私の意見では、システムの適切な分解と変更管理の方法は、私たちのハードワークの良い助けです。

提示された資料がお役に立てば幸いです。 JavaJamでのRESTのようなAPIの設計に関する私のレポートも参照してください。 こちらは投稿へのリンクです。