著者：Pan Shengwei (Shimian)
API (Application Programming Interface) は、デジタルエコシステム内のアプリケーションを橋渡しし、企業の運用効率の向上と企業ビジネスのデジタル化の鍵となります。API ファーストアプローチは、広く採用され認識されている新しい開発アプローチです。API ファーストアプローチでは、アプリケーションシステムは API を中心に設計されます。アプリケーションまたはサービスが構築および統合される前に、API は、実行に必要なすべてを考慮して定義および設計されます。マイクロサービスアーキテクチャは、このアプローチを典型的に採用しています。このようなアーキテクチャでますます多くのマイクロサービスが開発されるにつれて、API の量は指数関数的に増加し、API ファーストアプローチのメリットと重要性はますます自明になっています。
API ファーストは、他のコンポーネントよりも API の開発を優先して、シームレスなシステム統合と効率的な DevOps プラクティスを促進します。これに対して、従来のコードファーストアプローチでは、API はアプリケーション開発の最後に追加されるため、統合が困難になり、効率が低下します。
以下に、業界で言及されている API ファーストの実践についての原則のいくつかを示します。
1. 基礎としての API 設計の使用：API ファーストアプローチでは、API がすべての出発点となります。したがって、API は開発者、テスター、パートナー、エンドユーザーなど、すべてのステークホルダーのニーズを満たすように、慎重に計画および設計する必要があります。
上流および下流のステークホルダー
2. 一貫性と再利用性：API は、プロジェクトとアプリケーション間で一貫性があり、再利用できるように設計される必要があります。これにより、API が標準化され、開発が促進され、ソリューションのスケーラビリティが向上します。
3. コラボレーションとドキュメント：API ファーストアプローチは、開発チーム、ビジネスステークホルダー、および外部パートナー間のコラボレーションを重視しています。API を効果的に使用する方法を誰もが理解できるようにするには、包括的なドキュメントが不可欠です。
4. テスト駆動型開発：API に対して厳格なテストを早期に実行して、開発中に問題を特定して解決します。これにより、高い品質基準が維持され、後の段階でのコストのかかるエラーのリスクを減らします。
上記の原則は、API ライフサイクルの大部分を網羅しています。これらの原則から、API の設計と開発は簡単ではないことは明らかです。では、API ファーストアプローチはどのようなメリットをもたらすのでしょうか。それらのいくつかを下に挙げます。
• 開発体験の向上：適切に設計された API と詳細なドキュメントにより、開発者は API を理解し、実装しやすくなります。
• 効率的な開発とコラボレーション：API の説明とモックレスポンスに基づいて、開発者は効率的に共同作業でき、テストチームは事前にテストケースを準備できます。また、フロントエンドチームは予定より早くページを設計でき、バックエンドチームは独自のインターフェイスを同時に開発できます。マイクロサービス開発の場合、チームはさまざまなコンポーネントを並行して作業することで、全体的な開発を加速できます。
共同作業しているチームは、互いの開発進捗を妨げることはありません。
• 柔軟性と統合の容易さ：一貫性があり、再利用可能でスケーラブルな API によってサードパーティのサービス、プラットフォーム、アプリケーションとスムーズに統合することで、変化するニーズに迅速に対応できます。これにより、より一貫した統合されたエコシステムが促進されます。E コマースや自動車業界では、これを活用して、統合をより簡単かつ低コストにする機能オープンプラットフォームを構築できます。
• 自動化とイノベーション：特定の管理のもと、API を通じて完全な操作とデータが公開されます。これに基づいて、より多くの自動化ツールを開発して効率を向上させることができ、完全な DevOps が可能になります。この意味で、API は自動化とイノベーションの礎です。
• セキュリティ：セキュリティは、API 設計の初期段階で考慮されます。標準化され、一貫性のある API は、統合セキュリティポリシーの実装に役立ちます。さらに、API は提供される機能の範囲と境界を定義するため、チームは最小権限の原則に基づいて、アクセス可能な機能とデータをより適切に制御できます。
このセクションでは、Alibaba Cloud の API Gateway サービスのポリシーに基づいた、Alibaba Cloud での API ファーストの実践について説明します。
API Gateway には多くのポリシーがあります。
API Gateway から開発されたサービスとして、クラウドネイティブ API Gateway には、セキュリティ、トラフィックガバナンス、API / 操作の使用に関するさまざまなポリシーもあります。これらのポリシーを効果的に管理するために、さまざまなエンティティ (ゲートウェイ、ルート、サービス、ドメイン名など) に柔軟に適用するための共通のポリシー抽象化方法を設計しました。
このソリューションは、Policy モデルと PolicyAttachment モデルの 2 つのモデルに基づいています。Policy モデルは、すべてのポリシーの詳細とルールを定義します。このモデルを使用して、ポリシーを追加、削除、変更、およびクエリすることができます。このモデルは柔軟性と管理性を保証します。
ポリシー管理のためのモデル設計
API Gateway ポリシーは、セキュリティ管理ポリシーと API / 操作ポリシーの 2 つのカテゴリに分類されます。セキュリティ管理ポリシーは、IP アドレスの拒否リスト / 許可リスト、コンシューマー認証、グローバル認証ポリシーなどのセキュリティ機能を管理します。API / 操作ポリシーの例には、タイムアウト、再試行、オリジン間リソース共有 (CORS)、リダイレクトポリシーが含まれます。次のコード・スニペットは、サンプルポリシーを示しています。
{
"policyId": "policy1",
"name": "IP address blacklist policy",
"description": "Prohibit access from specific IP addresses",
"type": "security",
"rules": {
"blacklist": ["192.168.1.1", "10.0.0.1"]
}
}これらのポリシーを特定のエンティティ (ゲートウェイ、ルート、サービス、ドメイン名など) に適用するには、PolicyAttachment モデルを導入しました。このモデルは、定義されたポリシーを特定のエンティティにバインドするために使用されます。次の例では、ポリシーをサービスにバインドします。
{
"attachmentId": "attachment1",
"policyId": "policy1",
"entityType": "service",
"entityId": "serviceA"
}前述のモデルとは別に、ユーザーがポリシーの作成、取得、更新、削除、アタッチ、デタッチを行えるように、一連の RESTful API 操作を開発しました。次のコードは、拒否リストポリシーの例を示しています。
{
"name": "IPBlacklist",
"type": "security",
"rules": {
"blacklist": ["192.168.1.1", "10.0.0.2"]
}
}次の例は、API Gateway インスタンスにポリシーをアタッチする方法を示しています。
POST /api/policy
Content-Type: application/json
{
"name": "IPBlacklist",
"description": "gateway",
"config": {
"name": "IPBlacklist",
"type": "security",
"rules": {
"blacklist": ["192.168.1.1", "10.0.0.2"]
}
},
"attachResourceIds":[
"gatewayId1",
],
"attachResourceType": "Gateway",
"environmentId": "environmentId1",
"gatewayId": "gatewayId1"
}このような統合ポリシー管理システムは、システムの柔軟性と拡張性を高めるだけでなく、ビジネスのセキュリティと管理性を向上させます。
これに基づいて、API Gateway の基本的な API 設計方法を提供します。
OpenAPI 仕様 (OAS) は、RESTful API が定義および記述される標準形式です。次に、OAS に基づくポリシー管理 API モデルの例を示します。
openapi: 3.0.0
info:
title: Policy Management API
version: v1
servers:
- url: /api
paths:
/policies/{policyId}:
get:
summary: Get details of a specific policy.
operationId: getPolicy
parameters:
- name: policyId
in: path
required: true
description: The ID of the policy to retrieve.
schema:
type: string
responses:
'200':
description: Successful response with the policy details.
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
components:
schemas:
Policy:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-timeポリシー管理 API を設計した後、API ファーストアプローチの実装に役立つように、ライフサイクル全体で API を管理できるようにする必要があります。このセクションでは、Alibaba Cloud のクラウドネイティブ API Gateway サービスを例に、完全な API ファースト開発サイクルを説明します。
クラウドネイティブ API Gateway は、API を中心に動作します。最初に作成される API はポリシー管理 API で、これは、OAS または Swagger に準拠したデータをインポートするか、コンソールで手動で作成できます。手動の作成を見てみましょう。
クラウドネイティブ API Gateway コンソールでの API の作成
API が作成されると、コンソールで操作の作成が求められます。この例では、ポリシー管理 API のリソースを追加、削除、変更、クエリする操作を作成します。
クラウドネイティブ API Gateway コンソールでの操作の作成
事前に API を設計しているため、操作の作成時には、設計に従ってメタデータを入力するだけですみます。
ドキュメントは API ファーストアプローチの不可欠な部分です。したがって、操作を変更するたびに、対応するドキュメントを同時に更新する必要があります。操作の完全なメタデータを入力すると、関連するドキュメント、SDK、および仕様がリアルタイムで更新されます。たとえば、リクエストボディに JSON スキーマが指定されていない場合、API 操作ドキュメントの詳細な内容が生成される際にドキュメントがわかりにくくなります。また、JSON スキーマの標準的な内容が繰り返されることもわかります。API Gateway は、スキーマ情報の生成に役立つ機能を提供しています。
クラウドネイティブ API Gateway コンソールでの操作の作成
すべてのフィールドに入力したら、[追加] をクリックします。次に、すべての操作に対してアクションを繰り返します。次の図は、完全な API を示しています。
SDK とドキュメントをダウンロードして、事前に設計された API が開発プロセスの高速化と開発体験の向上にどのように役立つかを確認しましょう。
クラウドネイティブ API Gateway コンソールで生成された SDK とドキュメント
Java 用 SDK で結果を確認する
この例では、バックエンドがないため、API デバッグは実行されません。ただし、共同作業者はそれぞれの開発作業に必要なものを持っています。
さらに、コンソールにはモック機能があり、共同作業者による開発とデバッグを容易にします。
API モック機能は、API のレスポンスをモックします。これにより、ビジネスロジック全体が開発される前に、API が期待どおりに機能するかどうかを確認できます。必要な手順は 2 つだけです。API 操作とリクエストに対するレスポンスを定義することと、モックされたデータを公開することです。
API Gateway コンソールでの API モックの設定
API Gateway コンソールでのモックデータの公開
公開後、コンソールで API をオンラインでデバッグできます。
API Gateway コンソールでの API のデバッグ
デバッグする操作を見つけ、直接デバッグします。モックされたデータが返されます。これにより、共同開発の効率が大幅に向上します。
ドキュメントとモック機能を使用した API のデバッグ
API モックを使用すると、フロントエンド、バックエンド、QA、およびその他の依存するビジネスチームが、テスト、クライアントアプリケーション、およびサーバーの実装について並行して作業できます。
API データを OAS 3.0 形式でエクスポートし、Swagger Codegen を使用してサーバーサイドのコードフレームワークをすばやく生成し、開発を加速できます。
Swagger Codegen とは
その間、API ロジックを実装し、バックエンドシステムと統合する必要があります。コーディング、セキュリティ、パフォーマンスの最適化に関するベストプラクティスに従ってください。ここでは詳細には触れません。
API の開発が完了したら、API とそのバックエンドサービスをテスト環境に公開し、モックサービスをテスト環境の実際のバックエンドサービスに切り替えることができます。テスト環境を使用すると、QA、フロントエンド、およびその他の関連部門と共に、機能、パフォーマンス、セキュリティの観点から API を品質基準に従って完全にテストできます。
テストシステムとの統合を容易にするために、API 用の自動テストツールを構成する必要があります。このようにして、API 操作の正確性、パフォーマンス、およびセキュリティを日常的に保証できます。
また、API のセキュリティ保護ポリシーを設定し、API のパフォーマンスに応じてトラフィック保護などのスロットリングポリシーを設定し、セキュリティ認証ルールを設定し、ポリシー機能の検証を完了する必要があります。
適切なトラフィック保護ポリシーの設定
さまざまなコンシューマーに現在の API へのアクセスを許可できる
これらの準備が完了したら、API を公開し、デプロイできます。
API 管理ライフサイクルでは、API セキュリティとトラフィック保護ポリシーもまた、非常に重要です。API はシステム間の通信の入り口としてだけでなく、セキュリティとトラフィック保護のための最初の防衛線としても機能します。Alibaba Cloud API Gateway は、セキュリティの強化と API の安定性の確保に役立つさまざまなプラグインとポリシーを提供しています。
クラウドネイティブ API Gateway のセキュリティプラグイン
拒否リストや許可リストの設定：API で拒否リストまたは許可リストを設定して、アクセスリクエストの権限を効果的に制御できます。拒否リスト / 許可リストプラグインを使用すると、ゲートウェイ、ドメイン名、およびルートレベルでクライアント IP アドレスの拒否リストと許可リストを設定して、特定の IP アドレスからのアクセスリクエストを拒否 / 許可できます。柔軟な設定により、API のきめ細かいアクセス制御が可能になります。
クラウドネイティブ API Gateway の認証プラグイン
きめ細かい権限制御：API にきめ細かい権限制御を実装して、ユーザーが許可されたリソースにのみアクセスできるようにします。クラウドネイティブ API Gateway は、グローバル認証、ルート設定認証、およびコンシューマー認証をサポートし、API アクセス制御、セキュリティ保証、およびポリシー管理を保証します。クラウドネイティブ API Gateway で使用される認証プラグインを次に示します。
クラウドネイティブ API Gateway のさまざまなポリシー
きめ細かいトラフィック制御：クラウドネイティブ API Gateway は、API や操作に固有のトラフィック制御と同時実行制御をサポートしています。これにより、リクエストトラフィックを効果的に制御および監視できるため、突発的または悪意のあるトラフィックによるシステムの過負荷を防ぎます。きめ細かい制御は、単一ユーザーのリクエスト頻度を制限し、バックエンドサービスのパフォーマンスを保護するだけでなく、実際の負荷に基づいてポリシーを動的に調整し、リソース割り当てを最適化して、API サービスが並行性の高いシナリオでもスムーズに実行できるようにします。
API Gateway は、カナリアリリースとエンドツーエンドカナリアリリース機能を提供し、リスクや影響を制御するのに役立ちます。API 公開プロセスは、CI / CD 統合を通じてさらに自動化することができます。デフォルトでは、クラウドネイティブ API Gateway は、CloudMonitor や Prometheus などの組み込みの監視および可観測機能を提供しています。これにより、運用プロセスでの API のパフォーマンスと使用状況を監視することができます。監視とアラートを使用して、API の安定性を確保し、ビジネスの SLA 要件を継続的に満たすことができます。
API ファーストアプローチは、ソフトウェア開発において API を重視して、システムの柔軟性、保守性、およびスケーラビリティを確保します。API は、要件の設計と共同開発から公開と O&M に至るまで、ライフサイクル全体を通して一貫して重視されます。
クラウドネイティブ API Gateway は、API ファーストをよりよく実践するのに役立ちます。
このセクションでは、API Gateway を使用した運用環境に基づいた API 設計に関するいくつかの提案を示します。
API 設計ではバージョンの概念が使用されます。同じバージョンの API の場合、API の変更ごとに、API の上位互換性、つまり以前のクライアントが新しいバージョンに正常にアクセスできるかどうかを考慮する必要があります。
• 新しいオプションのフィールドを追加します。
• 既存のメソッド、フィールド、リスト値は削除も変更もしません。
• API 操作が変更されないことを前提として、権限がない限り API セマンティクスは変更しません。
API のアップグレードを行う際は、既存のユーザーに変更による非互換性の問題が発生するかどうかを検討する必要があります。
非互換性が引き起こされる変更がある場合は、API のメジャーバージョンをアップグレードし、クライアントも同時にアップグレードする必要があります。このプロセスは非常に長くなります。頻繁な互換性のないアップグレードは API ユーザーの許容範囲ではないため、適切な API 設計が重要です。API 設計のプロセスでは、公開する前に潜在的なリスクを発見するために、自分の API 設計を徹底的に検証できます。
ソフトウェアのアップグレードや変更に関しては、OpenAPI 仕様では、基本情報の記述として API のバージョンを指定できます。標準のバージョン管理方法により、新機能の導入時や主要な変更時に API の安定性を確保し、既存のユーザーやクライアントアプリケーションが変更の影響を受けないようにします。この下位互換性は、長期的なユーザーの信頼とアプリケーションの継続性を維持するために重要です。さらに、API のバージョン管理により、API ユーザーにスムーズなアップグレードパスを提供できるため、開発者とユーザーは新しいバージョンに徐々に移行して、1回限りの完全アップグレードによるリスクを回避することができます。
マイクロサービスアーキテクチャは、今日ますます普及しています。このようなアーキテクチャでは、サービスは多数の外部 API に依存しており、優れた API ドキュメントの重要性は計り知れません。正確かつ最新の API ドキュメントは、開発者に明確なインターフェイスの説明とコード例を提供し、誤用や間違いを大幅に減らすことができます。さらに、開発の効率を大幅に改善し、コミュニケーションを減らし、問題解決を加速することによって敏捷な開発を支えます。
JDK ArrayList ドキュメント
これが、優れた API が「もつ」理由の 1 つです。上記の例から、優れた API ドキュメントが API の機能と実装を説明して適切な例を提供し、リスクと注意事項をリストしていることがわかります。これらはすべて、ユーザーが API の適用可能なシナリオを事前に特定するのに役立ちます。
API が多すぎるサービスでは、ユーザーや管理者のコストが増加します。したがって、各 API は追加前に厳格に審査されます。新しい API を作成する代わりに、適切に設計された API と API の組み合わせで新しい要求に対応するよう試みます。一度 API が公開されると、ユーザーとクライアントはそれを統合し始めます。つまり、依存関係が増加し、公開停止や変更は多くの後続作業を引き起こします。
API ファーストでは、開発者は API 設計により多くの労力を費やす必要があります。総合的な計画と設計が求められるため、開発の後半で試行錯誤を行うチャンスがなくなる可能性があります。さらに、後に必要になる調整によって開発が遅れ、特に多数の API がある場合には、設計、管理、および保守における問題が引き起こされる可能性もあります。
並列開発により、依存関係とボトルネックが軽減され、機能をより迅速に提供できるようになります。包括的な API 管理ツールで、API 管理コストを効果的に削減することもできます。公開後の製品エクスペリエンスなど、後の開発段階で、API ファーストはより多くのメリットをもたらします。たとえば、システムを外部システムやサードパーティアプリケーションとより簡単かつ効率的に統合できます。セキュリティとスケーラビリティが早期に考慮されるため、システムはより安全で使いやすくなります。さらに、API を通じて公開されたデータを活用することで、エンジニアやユーザーのイノベーションが促進されます。そのため、初期の開発はやや遅く感じられるかもしれませんが、全体の開発プロセスは短縮され、製品の品質も向上します。
AI、ミニプログラム、サーバーレスアプリケーションなどのソフトウェアテクノロジーの急速な発展に伴い、API ファーストの開発アプローチでは、アプリケーションをこれらのテクノロジーとより柔軟に統合できます。API によって、AI サービスとの連携と、ミニプログラムやファンクションコンピューティングサービスとのコミュニケーションの両方を迅速に実現できます。これは、製品開発を加速するだけでなく、試行錯誤のコストを削減し、企業が絶えず変化する市場で競争力を維持するための強力なサポートを提供します。
The Era of Self-Built DeepSeek Has Arrived: How to Efficiently Implement Web Search
547 posts | 52 followers
FollowRegional Content Hub - March 8, 2024
Regional Content Hub - August 5, 2024
Regional Content Hub - February 26, 2024
Alibaba Cloud Japan - August 7, 2024
Regional Content Hub - March 8, 2024
Regional Content Hub - February 26, 2024
547 posts | 52 followers
Follow
API Gateway
API Gateway provides you with high-performance and high-availability API hosting services to deploy and release your APIs on Alibaba Cloud products.
Learn More
Microservices Engine (MSE)
MSE provides a fully managed registration and configuration center, and gateway and microservices governance capabilities.
Learn More
Cloud-Native Applications Management Solution
Accelerate and secure the development, deployment, and management of containerized applications cost-effectively.
Learn More
Database Gateway
A tool product specially designed for remote access to private network databases
Learn MoreMore Posts by Alibaba Cloud Native Community