REST API 及其架构

はじめに

今日の Web 開発の世界では、API (アプリケーション プログラミング インターフェイス) が、異なるソフトウェア システム間の通信を可能にする上で重要な役割を果たしています。最も広く使用されているタイプの API の 1 つは、Representational State Transfer の略である REST API です。 REST API は、スケーラブルで保守性が高く、効率的な Web サービスを構築するための標準になっています。このブログでは、REST API とは何か、その原理、アーキテクチャ、コンポーネント、およびそれらを効果的に設計および実装する方法について詳しく説明します。

REST API とは何ですか?
REST (Representational State Transfer) は、ネットワーク化されたアプリケーションを設計するためのアーキテクチャ スタイルです。これはステートレスなクライアント/サーバー通信モデルに依存しており、標準の HTTP メソッドに基づいています。 REST API を使用すると、さまざまなアプリケーションが、単純な規則セット、つまりルールを使用してインターネット上で通信できるようになります。

REST API は、HTTP リクエストを送信し、HTTP レスポンスを受信することによって、クライアント (ブラウザや携帯電話などの Web またはモバイル アプリケーション) がサーバーと対話できるようにするインターフェイスです。サーバーは、ユーザー プロフィールから画像やブログ投稿まで、あらゆるリソースへのアクセスを提供します。
REST の重要な原則
RESTful であるとみなされるには、API に次の 6 つの原則が必要です:

1. クライアントサーバーアーキテクチャ: クライアントとサーバーは互いに独立している必要があります。クライアントはユーザー インターフェイスとユーザー エクスペリエンスを担当し、サーバーはバックエンド ロジック、データ ストレージ、および処理を処理します。
2. ステートレス性: クライアントからサーバーへの各リクエストには、リクエストを理解して処理するために必要なすべての情報が含まれている必要があります。サーバーはリクエスト間のクライアント情報を保存しません。これにより、サーバーの設計が容易になり、拡張性が向上します。
3. キャッシュ可能性: サーバーからの応答はキャッシュ可能かキャッシュ不可能かを明確に定義する必要があります。応答がキャッシュ可能であれば、クライアントは今後のリクエストで応答データを再利用できるため、サーバーの負荷が軽減され、パフォーマンスが向上します。
4. 統一インターフェイス: REST API は、リソースと対話するための一貫した標準化された方法を提供する必要があります。これは 4 つの副原則によって実現されます。  - リソースの識別: リソースは URI (Uniform Resource Identifier) を使用して識別されます。  - 表現によるリソースの操作: クライアントは、リクエストで表現 (JSON、XML など) を送信することでリソースと対話します。  - 自己記述的なメッセージ: 各リクエストと応答には、メッセージの処理方法を説明するのに十分な情報が含まれている必要があります。  - アプリケーション状態のエンジンとしてのハイパーメディア (HATEOAS): クライアントは、応答で提供されるハイパーリンクを使用して API を動的に移動する必要があります。
5. 階層化システム: アーキテクチャでは、クライアントがこれらの層を意識することなく、クライアントとサーバーの間でキャッシュ層、負荷分散層、セキュリティ層などの中間層を使用できる必要があります。
6. コード オン デマンド (オプション): サーバーは、クライアント側で実行される JavaScript などの実行可能コードを送信することで、クライアントの機能を拡張できます。これは REST のオプションの制約です。

REST API アーキテクチャ
REST API のアーキテクチャは、クライアントとサーバー間の通信を確立するために連携して機能するいくつかの主要なコンポーネントで構成されています。

1. リソース: リソースは REST API の中核概念です。これらは、ユーザー、製品、注文など、API がアクセスを提供するデータまたはオブジェクトを表します。各リソースは一意の URI によって識別されます。

2. HTTP メソッド: REST API は標準の HTTP メソッドを使用して、リソースに対して CRUD (作成、読み取り、更新、削除) 操作を実行します。
    - GET: リソースからデータを取得します。
    - POST: リソース(DB)に新しいデータ変更を作成します。
    - PUT: データ(DB)内の既存のレコードを更新します。
    - DELETE: DB から特定のデータを削除します。
    - PATCH: 既存のデータを部分的に更新します。
    - オプション: リソースに対してサポートされている HTTP メソッドを取得します。

3. HTTP ステータス コード: REST API は、標準の HTTP ステータス コードを使用してリクエストの結果を示します。一般的なステータス コードは次のとおりです:
    - 200 OK: リクエストは成功しました。
    - 201 作成: 新しいリソースが正常に作成されました。
    - 204 コンテンツなし: リクエストは成功しましたが、返されるコンテンツがありません。
    - 400 Bad Request: リクエストの形式が間違っているか、無効です。
    - 401 Unauthorized: クライアントはリソースにアクセスするには認証する必要があります。
    - 404 見つかりません: 要求されたリソースが見つかりませんでした。
    - 500 内部サーバー エラー: サーバーで予期しないエラーが発生しました。

4. 表示格式：REST API 支持各种数据交换表示格式，包括 JSON（JavaScript 对象表示法）、XML（可扩展标记语言）和 HTML。 JSON 是最常用的格式，因为它简单且与 JavaScript 兼容。

5. 端点：端点是定义可以从服务器访问特定资源的位置的 URL。每个端点对应于一个特定的资源，通常使用名词而不是动词来设计（例如/users、/products）。

设计 RESTful API

设计 RESTful API 涉及多个步骤，以确保其遵守 REST 原则并为客户提供无缝体验。以下是设计 REST API 的一些最佳实践：

1. 对端点使用名词：端点应以资源（名词）而不是操作（动词）命名。例如，使用 /users 来表示用户集合，而不是 /getUsers。

2. 正确使用 HTTP 方法：为每个操作使用正确的 HTTP 方法。例如，使用 GET 检索数据、POST 创建数据、PUT 更新数据、DELETE 删除数据。

3. 实现过滤、排序和分页：对于返回资源列表的端点，实现过滤、排序和分页以提高性能并为客户端提供更多控制。使用 ?sort=name、?page=2 或 ?limit=10 等查询参数来实现此目的。

4. 对 API 进行版本控制：始终对 API 进行版本控制，以在不破坏现有客户端的情况下处理更改。在 URL 中（例如 /api/v1/users）或标头中包含版本号。

5. 提供有意义的 HTTP 状态代码：返回适当的 HTTP 状态代码以指示请求的结果。避免每次回复都使用 200 OK。

6. 使用超媒体 (HATEOAS)：在响应中包含链接，以允许客户端动态导航 API，而无需硬编码 URL。

7. 确保安全：使用 HTTPS 加密传输中的数据来保护您的 API。实施身份验证（例如 OAuth、JWT）和授权来控制对资源的访问。

8. 优雅地处理错误：提供有意义的错误消息和 HTTP 状态代码，以帮助客户端了解出了什么问题。创建可重复使用的错误格式，其中包含错误代码、消息和可能的解决方案等详细信息。

REST API 设计示例

让我们考虑一个用于管理书籍集合的简单 REST API 示例：

1. 端点：/api/v1/books
2. GET /api/v1/books：从 db 获取所有书籍的列表。  - POST /api/v1/books：在数据库中创建一本新书。
3. 端点：/api/v1/books/{id}
4. GET /api/v1/books/{id}：按 ID 返回特定书籍。  - PUT /api/v1/books/{id}：通过 ID 更新特定书籍。  - DELETE /api/v1/books/{id}：按ID删除特定书籍
5. 错误处理示例：
6. 如果客户请求一本不存在的书：   - 响应：404 未找到   - 身体：身体看起来像这样

实现 REST API

要实现 REST API，您可以使用各种编程语言和框架。以下是结合使用 Node.js 和 Express.js 的示例：

以上是REST API 及其架构的详细内容。更多信息请关注PHP中文网其他相关文章！