Restful API は現在、一連のインターネット アプリケーションの比較的成熟した API 設計概念です.Rest はアーキテクチャ上の制約と原則のセットです.Rest の制約と原則に準拠するアーキテクチャは、Restful アーキテクチャと呼ばれます.Restful アーキテクチャには明確な構造があります. 、規格に準拠している、分かりやすい、展開しやすいなど、採用サイトが増えています！
目次
3.6 キャッシュ可能 (クライアントは応答の内容をキャッシュできます)
1. 背景
ウェブサイトの開発は、ソフトウェア開発モデルを完全に採用できます。しかし、従来、ソフトウェアとネットワークは 2 つの異なる分野であり、ソフトウェア開発は主にスタンドアロン環境用であり、ネットワークは主にシステム間の通信用であり、交差するものはほとんどありませんでした。インターネットの台頭により、この2つの分野が融合し始めた今、インターネット環境で使用するソフトウェアをどのように開発するかを考えなければなりません。
RESTful アーキテクチャは、現在最も人気のあるインターネット ソフトウェア アーキテクチャです。構造が明確で、規格に準拠しており、わかりやすく、展開しやすいことから、ますます多くのWebサイトで採用されています。
ただし、RESTful アーキテクチャとは正確には何であるかを明確にするのは簡単ではありません。次に、私が理解している RESTful アーキテクチャについて説明します。
REST という言葉は、2000 年の博士論文で Roy Thomas Fielding によって提案されました。Fielding は非常に重要な人物であり、HTTP プロトコル (バージョン 1.0 および 1.1) の主要な設計者であり、Apache サーバー ソフトウェアの作成者の 1 人であり、Apache Foundation の初代会長でもあります。そのため、彼の論文が発表されるとすぐに注目を集め、インターネットの発展に大きな影響を与えました。
2. 基本コンセプト
フィールディングは、Representational State Transfer の略であるインターネット ソフトウェア REST のアーキテクチャ原則に名前を付けました。このフレーズの私の翻訳は、「プレゼンテーション層の状態変換」です。アーキテクチャが REST 原則に準拠している場合、それは RESTful アーキテクチャと呼ばれます。
RESTful アーキテクチャを理解するための最善の方法は、Representational State Transfer というフレーズの意味と、各単語が何を表しているかを理解することです。名前がわかれば、RESTがどのような設計なのか理解するのは難しくありません。
2.1 リソース
REST名「Representation Layer State Transformation」では件名が省略されています。「プレゼンテーション層」とは、実際には「リソース」の「表現層」を指します。
いわゆる「リソース」は、ネットワーク上のエンティティ、またはネットワーク上の特定の情報です。テキスト、写真、歌、サービス、つまり具体的なものです。URI (Uniform Resource Locator) でそれを指すことができ、各リソースは特定の URI に対応します。このリソースを取得するには、その URI にアクセスするだけで、URI が各リソースのアドレスまたは一意の識別子になります。
いわゆる「インターネットサーフィン」とは、インターネット上の一連の「リソース」と対話し、その URI を呼び出すことを意味します。
2.2 表現
「リソース」は、さまざまな外部表現を持つことができる情報エンティティです。「資源」を具体的に提示する形を、その「提示」と呼びます。
たとえば、テキストは txt 形式、HTML 形式、XML 形式、JSON 形式、またはバイナリ形式で表現でき、画像は JPG 形式または PNG 形式で表現できます。
URI は、リソースの形式ではなく、リソースのエンティティのみを表します。厳密に言えば、一部の URL の末尾にある「.html」サフィックスは不要です。このサフィックスは形式を示し、「プレゼンテーション レイヤー」のカテゴリに属し、URI は「リソース」の場所のみを表す必要があるためです。その具体的な表現形式は、Accept フィールドと Content-Type フィールドを使用して HTTP 要求のヘッダー情報で指定する必要があり、これら 2 つのフィールドは「プレゼンテーション層」の説明です。
2.3 状態遷移 (State Transfer)
Web サイトへのアクセスは、クライアントとサーバー間の対話プロセスを表します。このプロセスでは、データと状態の変更が必ず関係します。
インターネット通信プロトコルの HTTP プロトコルは、ステートレス プロトコルです。これは、すべての状態がサーバー側で保持されることを意味します。したがって、クライアントがサーバーを操作したい場合は、何らかの手段を使用してサーバーを「状態転送」(State Transfer) する必要があります。そして、この変換はプレゼンテーション層に基づいているので、「プレゼンテーション層の状態変換」です。
クライアントが使用できるメソッドは、HTTP プロトコルのみです。具体的には、HTTP プロトコルには、操作モードを示す 4 つの動詞 (GET、POST、PUT、DELETE) があります。それらは 4 つの基本操作に対応します。GETはリソースの取得に使用され、POST は新しいリソースの作成に使用され (リソースの更新にも使用できます)、PUT はリソースの更新に使用され、DELETE はリソースの削除に使用されます。
2.4 コンセプトのまとめ
上記の説明に基づいて、RESTful アーキテクチャとは何かを要約しましょう。
(1) 各 URI はリソースを表します。
(2) このリソースのある種のプレゼンテーション層 (表現) が、クライアントとサーバーの間で転送されます。
(3) クライアントは、4 つの HTTP 動詞を使用してサーバー側のリソースを操作し、「プレゼンテーション層の状態変換」を実現します。
3.残りの設計原則
3.1 各 URI はリソースを表す
URI は、1 つのタイプのリソースのみを表します。
http://xxx.com/api/users; // すべてのユーザー情報を取得 http://xxx.com/api/teachers; // すべての教師情報を取得 http://xxx.com/api/areas; //すべての地域情報を取得する
3.2 同じリソースに複数の体現形がある
リソースは複数の形式 ( xml、json など) で返すことができます. クライアントが要求するとき、要求ヘッダーにパラメーターを設定し、指定されたタイプのデータを返すために restful を要求することができます. これは、RESTful のメタ原則です.インターフェイスが満たす必要があります。
Accept:application/xml リクエスト時にリターンフォームを xml に設定 ajaxリクエストを利用する場合は contentType:application/xml を設定する必要があります Accept:application/json リターンフォームをjsonに設定する必要があります ajaxリクエストを利用する場合はset contentType:application /json
3.3 すべての操作はステートレス
http リクエスト自体はステートレスであり、RESTful はステートレス http プロトコルに基づいているため、さまざまな RESTful リクエストもステートレスです。
これは次のように理解できます。プロトコルには、トランザクション処理のためのメモリ機能がありません。状態がないということは、後続の処理で前の情報が必要な場合に、それを再送信する必要があることを意味します。これにより、接続ごとに転送されるデータ量が増加する可能性があります。しかしその一方で、サーバーが以前の情報を必要としない場合、サーバーの応答はより高速になります。
たとえば、ブラウザがサーバーにリクエストを送信すると、サーバーは応答しますが、同じブラウザがサーバーに再度リクエストを送信すると、応答しますが、あなたが今のブラウザであることを認識していません。サーバーはあなたを覚えていません。
したがって、状態などのメモリ機能が必要な場合は、ブラウザの Cookie、セッション、およびトークン テクノロジを使用してそれを実現できます。
3.4 標準化された統一インターフェース
Rest インターフェイスの制約は次のように定義されます。
-
リソース識別: 操作対象のリソースが uri で示されることを意味し、操作を示す動詞はここに含めることはできません。
-
リクエスト アクション: リクエスト アクション (http メソッド) を通じて実行される操作を識別します。
-
応答情報;: 返されたステータス コードを通じて、この要求の実行結果を示します。
RESTful インターフェース仕様を満たさない通常のインターフェース:
- http://xxx.com/api/getallUsers; // すべてのユーザー情報を取得する GET リクエスト メソッド
- http://xxx.com/api/getuser/1; // GET リクエスト メソッド、1 で識別されるユーザー情報を取得
- http://xxx.com/api/user/delete/1 // 1 とマークされたユーザー情報を GET、POST で削除
- http://xxx.com/api/updateUser/1 // 1 で識別されたユーザー情報を更新する POST リクエスト メソッド
- http://xxx.com/api/User/add // POST リクエスト メソッド、新しいユーザーを追加
標準の統一された RESTful スタイル インターフェイス仕様:
- http://xxx.com/api/users; // すべてのユーザー情報を取得する GET リクエスト メソッド
- http://xxx.com/api/users/1; // 1で識別されるユーザー情報をGETリクエストで取得
- http://xxx.com/api/users/1; // 1 のマークが付いたユーザー情報を削除する DELETE リクエスト メソッド
- http://xxx.com/api/users/1; // PATCH リクエスト メソッド、1 で識別されるユーザー部分の情報を更新
- http://xxx.com/api/users; // 新しいユーザーを追加するための POST リクエスト メソッド
3.5 一貫したデータ形式を返す
返されるデータ形式には、ステータス、コード、情報、データなど、標準で必要なフィールドが少なくともいくつかあります。
3.6 キャッシュ可能 (クライアントは応答のコンテンツをキャッシュできます)
現在、インターフェイスは基本的にキャッシュ可能な機能を提供しています。つまり、インターフェイスの開発段階で、ブラウザがキャッシュできるかどうか、キャッシュの種類と有効な時間などを設定します。たとえば、強力なキャッシュとネゴシエートキャッシュの仕様はサーバー側の設定です。
4. API インターフェース設計仕様
4.1 URI 仕様
-
URL 名はすべて小文字にする必要があります
-
URL 内のリソース (リソース) 名は名詞である必要があり、複数形である必要があります
-
安静な URL を優先する必要があります
-
- URL には表示できません。アンダースコアに置き換える必要があります _
-
URL は人が読める形式にする必要があります
-
URL はサーバー アーキテクチャを公開してはなりません
http://xxx.com/api/male_users // 男性ユーザーを取得します。
http://xxx.com/api/male_users&sort=age_desc // 男性ユーザーを年齢の降順に取得します。
-
マルチレベルの URI を避ける
一般的な状況では、リソースには複数レベルの分類が必要なため、特定の作成者による特定のカテゴリの記事を取得するなど、複数レベルの URL を簡単に記述できます。
# GET /authors/12/categories/2
この種の URL は展開しにくく、セマンティクスが明確ではなく、意味を理解するのに時間がかかります。
さらに良いことに、最初のレベルを除くすべてがクエリ文字列で表現されます。
# GET /authors/12?categories=2
4.2 リクエスト方法
-
GET (SELECT): クエリ; サーバーからリソースを取得 POST (CREATE): 追加; サーバー上に新しいリソースを作成;
-
POST (CREATE): サーバー上に新しいリソースを作成します。
-
PUT(UPDATE): 更新; サーバー上のリソースを更新します (クライアントは、変更後に完全なリソースを提供します)。
-
PATCH(UPDATE): 更新; サーバー上の一部のリソースを更新します (クライアントは変更された属性を提供します);
-
DELETE(DELETE): 削除; サーバーからリソースを削除;
-
HEAD: リソースのメタデータを取得します。
-
オプション: クライアントが変更できるリソースのプロパティに関する情報を取得します。
4.3 フィルター情報
If there are many records, it is possible for the server for the server to return them all to the user. API は、返された結果をフィルター処理するためのパラメーターを提供します. 一般的なパラメーターは次のとおりです。
-
?limit=20: 返されるレコードの数が 20 であることを指定します。
-
?offset=8: 返されるレコードの開始位置が 8 であることを指定します。
-
?page=1&per_page=50: ページ 1 を指定し、ページあたりのレコード数は 50 です。
-
?sortby=name&order=asc: 返された結果が name 属性に従って昇順でソートされることを指定します。
-
?animal_type_id=2: フィルター基準を指定します。
4.4 ステータスコード
次の表に、一般的な HTTP ステータス コードを示します。
| ステータスコード | 説明 |
| 1xx | 委任要求が受け入れられ、処理を続行する必要があります |
| 2xx | リクエストは成功しました。リクエストが期待するレスポンス ヘッダーまたはデータ ボディが、このレスポンスとともに返されます。 |
| 3xx | リダイレクト |
| 4xx | クライアントによるエラー |
| 5xx | サーバーが原因のエラー |
HTTP API の設計において、頻繁に使用されるステータス コードとその具体的な説明は次のとおりです。
| ステータス コード | セマンティクス | 例証する |
| 200 | OK | リクエストが成功しました |
| 201 | 作成した | リクエストが完了し、1 つ以上のリソースが作成されました。最も一般的には、POST がリソースを作成するときに使用されます。 |
| 202 | 承認済み | リクエストは受信され処理されましたが、処理はまだ完了していません。通常、非同期処理の場合に使用されます。応答本文は、タスクのステータスを確認する場所をクライアントに伝える必要があります。 |
| 204 | コンテンツなし | リクエストは処理されましたが、返す情報がありません。PUT がリソースを更新するときによく使用されます (クライアントはリソースのすべての属性を提供するため、サーバーが返す必要はありません)。重要なメタデータがある場合は、ヘッダーに入れて返すことができます |
| 301 | 恒久的に移動 | 要求されたリソースは別の場所に完全に移動されており、後続のすべての要求は新しいアドレスに直接アクセスする必要があります。サーバーは新しいアドレスを Location ヘッダー フィールドに書き込みます。これは、クライアントが使用するのに便利です。クライアントが POST リクエストを GET に変更できるようにします。 |
| 302 | 一時的に移動した | 一時的なリダイレクト |
| 304 | 未変更 | 要求されたリソースは以前のバージョンと同じで、変更されていません。リソースをキャッシュし、条件付きリクエストと一緒に表示するために使用されます |
| 307 | 一時的なリダイレクト | ターゲット リソースは一時的に新しいアドレスに移動され、クライアントは操作するために新しいアドレスに移動する必要がありますが、要求されたメソッドを変更することはできません。 |
| 308 | 恒久的なリダイレクト | クライアントが元のリクエストのメソッドを変更できないことを除いて、301 に似ています。 |
| 400 | 要求の形式が正しくありません | 1. セマンティクスが間違っていて、現在のリクエストをサーバーが理解できない; 2. リクエスト パラメータが間違っている。 |
| 401 | 無許可 | 現在のリクエストには認証が必要です。 |
| 403 | 禁断 | サーバーは要求を理解しましたが、受け入れることを拒否しています。401 応答とは異なり、認証は役に立たず、要求を繰り返すべきではありません。これが HEAD リクエストではなく、サーバーがリクエストを実行できない理由を説明できるようにしたい場合は、拒否の理由をエンティティで説明する必要があります。もちろん、サーバーがクライアントに情報を取得させたくない場合は、404 応答を返すこともできます。 |
| 404 | 見つかりません | 要求されたリソースがサーバーで見つからなかったため、要求は失敗しました。 |
| 405 | メソッドは許可されていません | リクエスト ラインで指定されたリクエスト メソッドを使用して、対応するリソースをリクエストすることはできません。応答は、現在のリソースによって受け入れられる要求メソッドのリストを示す Allow ヘッダーを返す必要があります。PUT メソッドと DELETE メソッドはサーバー上のリソースに書き込むため、ほとんどの Web サーバーは、既定の構成では上記の要求メソッドをサポートしていないか、許可していません。このような要求に対しては 405 エラーが返されます。 |
| 406 | 受け付けできません | 要求されたリソースのコンテンツ プロパティが要求ヘッダーの条件を満たしていないため、応答エンティティを生成できません。 |
| 409 | 対立 | 要求されたリソースの現在の状態と競合するため、要求を完了できませんでした。 |
| 429 | リクエストが多すぎます | 不十分なリソース クォータまたはレート制限に達しました。 |
| 499 | クライアントクローズリクエスト | リクエストはクライアントによってキャンセルされました。 |
| 500 | 内部サーバーエラー | 内部サーバーエラー |
| 501 | 未実装 | サーバーは、現在の要求に必要な機能をサポートしていません。サーバーが要求されたメソッドを認識せず、リソースに対するその要求をサポートできない場合。 |
| 502 | 悪いゲートウェイ | ゲートウェイまたはプロキシとして機能しているサーバーが、要求を実行しようとしているときに、アップストリーム サーバーから無効な応答を受け取りました。 |
| 503 | サービスは利用できません | サーバーは、一時的なサーバー メンテナンスまたは過負荷のため、現在要求を処理できません。この状態は一時的なものであり、時間の経過とともに回復します。 |
| 504 | ゲートウェイ タイムアウト | ゲートウェイまたはプロキシとして機能するサーバーが、リクエストを実行しようとしたときに、アップストリーム サーバー (HTTP、FTP、LDAP などの URI で識別されるサーバー) またはセカンダリ サーバー (DNS など) からタイムリーな応答を受信できません。 . |
| 505 | HTTP バージョンがサポートされていません | 服务器不支持，或者拒绝支持在请求中使用的 HTTP 版本。 |
上面这些状态码覆盖了 API 设计中大部分的情况，如果对某个状态码不清楚或者希望查看更完整的列表，可以参考 HTTP Status Code。