しかし、プロジェクトが実際に開始された後、作者はいくつかの深刻な問題に遭遇しました。
1. 完全な API ドキュメントと仕様の欠如:
· API ドキュメントは不完全で誤りが多く、正確なリファレンスとして使用できません。
· 合意された API テスト プロセスがないため、バックエンド開発チームが予告なく API を自由に変更およびリリースすることができます。このような変更は多くの場合バグであり、API クライアントとの統合を破壊します。
2. 不適切な API フレームワークと検証:
バックエンド チームは不適切な Flask フレームワークを使用し、複雑なペイロード検証を独自に実装しましたが、そのほとんどはテストされていませんでした。
· 検証部分には、日付、タイムスタンプ、文字列形式の検証を含む大量のコードがありますが、完全にテストされていないため、プロジェクトの進行が大幅に遅くなります。
したがって、上記の問題を解決するには、API ドキュメントを修正して改善し、その正確性と完全性を確保する必要があります。また、コードの品質とテスト容易性を向上させるために適切な API フレームワークを確立し、問題のあるバージョンのリリースを防ぐために厳密な API 仕様を確立する必要があります。仕様を満たしていません。
API の設計とドキュメントを修正
上記で明らかになった問題から、開発チームが REST API と OpenAPI 仕様のベスト プラクティスを理解していないことがわかります。したがって、開発チームはまず OpenAPI とその仕組みを理解し、API ドキュメントを OpenAPI 仕様に統合して、API の予想される動作をより明確に理解する必要があります。
ドキュメントを OpenAPI 仕様に統合する過程で、以前の API 設計に多くの問題があることがわかりました。たとえば、カスタム日付形式では、以前はサーバーと UI にカスタム検証ロジックが必要でした。私たちは、日付を表すために OpenAPI でサポートされている ISO 標準に切り替えることで、この問題を解決しました。
さらに、一部のモードは柔軟性が高いため、検証がほとんど効果がありません。検証を改善するために、スキーマをリファクタリングし、エンティティごとに異なるエンドポイントを持つモデルを作成して、より使いやすくしました。
以前の設計では、HTTP メソッドとステータス コードが不適切に使用されていました。チームは GET メソッドと POST メソッドのみを使用し、すべての応答でステータス コード 200 を返します。この不適切な使用により、リソースを作成、削除、または更新しようとするときが不明確になります。この問題を解決するために、HTTP メソッドの使用を再定義し、リクエストの成功または失敗をより正確に示すために適切なステータス コードを正しく返すようにしました。
以前の設計のもう 1 つの制限は「エンドポイントの再利用」でした。コードを節約しているように見えますが、実際には実装の詳細が多すぎます。したがって、最初に API を設計してから実装を検討するという概念を重視する必要があります。
API 仕様と OpenAPI の統合は、プロジェクトにとって重要な転換点でした。その後、バックエンドと統合する前にモック サーバーを実行して UI を構築およびテストし、仕様に照らしてバックエンドの実装を検証することができました。 Prism を使用してモックサーバーを実行し、Dredd を使用してサーバーの実装を検証します (ただし、現在は Schemathesis を使用することを好みます)。これにより、プロジェクトをより明確かつ効率的に開発できるようになります。
APIリリースプロセスを修正
API ドキュメントがあっても、リリース前に API 仕様に照らしてテストされていない場合、ドキュメントの役割は限定的になってしまいます。ドキュメント自体は API がどのように動作するかを理解するのに役立ちますが、その真の力は、サーバーが正しく実装されていることを検証する検証ツールとしての機能にあります。
API サーバーが期待どおりに実行されていることを確認するために、Dredd テスト スイートを継続的統合サーバーに組み込みました。 Dredd の検証に合格し、API 仕様に準拠していない限り、新しいコードをマージして公開することはできません。このステップにより、チームは API サーバーに対する不注意な変更を回避できます。今後は、サーバーに対するすべての変更を事前に文書化する必要があり、マージまたは公開する前に API サーバーがこれらの変更に従っていることを確認する必要があります。このアプローチにより、サーバーの安定性と一貫性が保証されます。
適切な API 開発フレームワークを選択する
以前、チームは、Web アプリケーションを構築するための一般的な Python フレームワークである Flask フレームワークを使用して API サーバーを実装しました。彼らは基本的な Flask を使用して API を構築し、API ペイロードを検証するために多くのカスタム コードを作成しました。これは、経験の浅い API 開発者の多くが犯しやすい間違いです。
カスタム API 検証レイヤーを構築することは望ましくありませんが、このアプローチに過度に依存すると、車輪の再発明につながる可能性があります。 API には、ペイロードと URL (パスとクエリ パラメーター) を処理するための複雑な検証ロジックが必要であり、API 全体に実装する必要があります。したがって、独自の API 検証レイヤーを構築することに固執すると、最終的には API フレームワークを作成することになります。ただし、優れた API 開発フレームワークが数多く存在するため、その中から 1 つを選択してみてはいかがでしょうか。
特に Flask の場合、考慮すべきオプションがいくつかあります。しかし、すべてのフレームワークが同じように作られているわけではありません。たとえば、flasgger、restx (flask-restplus の後継)、flask-RESTful、flask-smorest などです。選択肢がたくさんある中で、どうやって決断を下すのでしょうか？
REST API 開発フレームワークを選択するときは、次の要素を考慮する必要があります。
· OpenAPI サポート: フレームワークにより、REST API の簡単な構築と API ドキュメントの自動生成が可能になり、ペイロード検証の正確性が保証されます。参照フレームワークには、Flasgger と flask-smorest が含まれます。
· 堅牢なデータ検証: ペイロードを検証するには、さまざまな属性やタイプを処理する堅牢なデータ検証ライブラリが必要です。ライブラリは、文字列形式 (ISO 日付と UUID) などのオプションおよび必須のプロパティと、厳格かつ緩和された型検証をサポートする必要があります。 Python エコシステムでは、pydantic と marshmallow は優れたデータ検証ライブラリであり、Flasgger と flask-smorest はマシュマロを使用できます。
包括的な検証: フレームワークは、リクエスト ペイロード、レスポンス ペイロード、URL パス パラメーター、および URL クエリ パラメーターの検証をサポートする必要があります。ライブラリによっては、リクエスト ペイロードのみを検証し、URL パラメータやレスポンス ペイロードを無視する場合があります。フレームワークが検証ルールを強制する方法を少なくとも 1 つ提供していることを確認してください。マシュマロを使用する場合、そのモデルを使用して応答ペイロードを直接検証できます。
· 成熟度: 成熟し、安定しており、コミュニティのサポートが活発に行われているライブラリを選択します。適切なドキュメントと、ユーザーの問題を迅速に解決できる機能が必要です。
上記の要素を評価した後、REST API のデータ検証を簡単に構築するためのマシュマロの使用をサポートする Flask プラグインである flask-smorest を選択しました。データ検証プロセスを簡素化し、カスタム コードの量を削減できます。リクエストとレスポンスのペイロードの両方が適切に検証されるようになり、marshmallow は URL クエリとパス パラメータの検証も処理します。
適切な API フレームワークを選択すると、API を機能させることができます。フレームワークが API レイヤーの詳細を処理するため、アプリケーションのビジネス ロジックとデータ モデルにより重点を置くことができ、その結果、開発速度が向上し、より優れたソフトウェアをより頻繁にリリースできるようになります。
優れた API を構築するためにすべてを考慮する
今日のインターネットでは、API はどこにでもあり、避けられません。ただし、優れた API を本当に構築するのは複雑な作業であり、読みやすく保守しやすいコードを作成するのと同じように、高品質で使いやすく、変更しやすいインターフェイスを構築することも API 開発における課題です。
高品質の API を提供するのは困難です。なぜなら、API はビジネス要件と一致している必要があるからです。つまり、クライアントとサーバーが同じ規則と仕様を使用する必要があり、そうでないと統合が困難になります。
この目標を達成するには、顧客の要件を収集し、要件を技術的な詳細に変換し、API を設計し、ドキュメントを作成し、適切な API フレームワークを選択して正しく使用し、API をテストし、実装が設計仕様を満たしていることを確認するなど、複数の側面を考慮する必要があります。これには、API のセキュリティ、展開、運用などの側面は含まれません。
ビジネスクリティカルな API の構築に関しては、若手開発者だけに任せないことをお勧めします。彼らは参加できますが、彼らの作業を指導する上級開発者が必要です。 API 開発の経験がない場合は、ベスト プラクティス パスに従ってください。まず API を設計し、次にドキュメントを作成し、仕様に従って実装し、検証します。車輪の再発明ではなく、適切なフレームワークを選択してください。
OpenAPI の学習、API テスト フレームワークの理解、API 開発フレームワークの調査などには時間がかかるかもしれませんが、それだけの価値はあります。そうしないと、API 統合とソフトウェア品質の問題の悪循環に陥り、プロジェクトの進行が妨げられ、問題解決に多大なコストが発生することになります。
十分なリソースと経験豊富な API 開発者がいる場合、API を正しく構築できる可能性が大幅に高まり、多額の費用を節約できます。また、APIの管理には、初期の開発コストや支出コストだけでなく、開発過程での隠れたコードの問題や、担当者の引継ぎが不透明であるなど、潜在的な危険性が潜んでいる問題も多くあります。したがって、Power Simple Integration では、API 管理ではサードパーティのツールを使用して、複数の役割が関与する API をワンストップで管理できるため、責任逃れを回避し、開発効率を向上できると考えています。
元のリンク: API ファーストによる市場投入までの時間の短縮 | Jose Haro Peralta 著 | 市場投入までの時間を短縮する API の優先順位 |