Web APIインターフェースとRestful仕様の詳細な説明

Web API インターフェースとは何ですか?

リクエスト メソッドを明確にし、対応するバックエンドに必要なパラメーターを指定して、バックエンドから応答データを取得するための URL リンクをリクエストします。

リクエスト メソッド: get、 post、put、patch. ...

リクエストパラメータ: json または xml 形式の key-value 型データ

応答結果: json または xml 形式で key-value 型データを返す

インターフェイスはどうやって書くのですか?

あるルール(仕様)を参考にURLリンクを記述し、そのルールに従ってリクエストメソッド、リクエストデータ、レスポンス結果を策定します

インターフェース仕様: webapiインターフェース仕様: restful

RESTful の紹介

REST はテクノロジとは何の関係もありません。ソフトウェア アーキテクチャ スタイルを表します。REST は Representational State の略です。 Transfer、中国語訳は「表現状態の転送」または「プレゼンテーション層の状態変換」です。

ドメイン名

api キーワードを使用してインターフェイス URL を識別します

https://api.example.com
https://example.org/api/

注: api という単語が表示された場合は、リクエストがURL リンクは完了前です

バックグラウンド データ インタラクションのバージョン

1. URL にバージョン情報を入力します (例:

https://api.example.com/v1/
https://api.example.com/v2/

v1、 v2 は異なるデータ バージョンを表します。 撤回では、データ リソースに複数のバージョンがあることが前提です。

2. リクエスト ヘッダーにバージョン情報を入れます。

url パス

インターネット上のあらゆるものをリソースとして捉え、それを名詞で表現します (通常は複数形)

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

URL 内リンク 報酬にはリソースを操作する動詞は表示されません

エラー デモンストレーション:https://api.baidu.com/delete-user

動詞は特別なインターフェイスに表示される可能性があります。一般に、インターフェイスには明確なリソースがないか、動詞がインターフェイスの中核的な意味です。

https://api.baidu.com/place/search
https://api.baidu.com/login

メソッド要求メソッド

GET: リソースを取得します (1 つ)または複数のアイテム) をサーバーから取得します)

POST: サーバー上に新しいリソースを作成します

PUT: サーバー上のリソースを更新します (クライアントは、変更された完全なリソースを提供します)

PATCH: サーバー上のリソースを更新します (クライアント 変更された属性はクライアントによって提供されます)

DELETE: サーバーからリソースを削除します

フィルタリング

url のアップロード パラメーターの形式で検索条件を渡します

https://api.example.com/v1/zoos?limit=10：指定返回记录的数量
https://api.example.com/v1/zoos?offset=10：指定返回记录的开始位置
https://api.example.com/v1/zoos?page=2&per_page=100：指定第几页，以及每页的记录数
https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序
https://api.example.com/v1/zoos?animal_type_id=1：指定筛选条件

ステータス コード

200 OK - [GET]: サーバーは要求されたデータを正常に返します。この操作は冪等です (Idempotent)。

201 CREATED - [POST/PUT/PATCH]: ユーザーはデータを正常に作成または変更しました。

202 Accepted - [*]: リクエストがバックグラウンド キュー (非同期タスク) に入ったことを示します。

204 NO CONTENT - [DELETE]: ユーザーはデータを正常に削除しました。

301: 永続的なリダイレクト

302: 一時的なリダイレクト

400 無効なリクエスト - [POST/PUT/PATCH]: ユーザーが発行したリクエストにエラーがあり、サーバーが続行されませんでした データの作成または変更の操作は冪等です。

401 Unauthorized - [*]: ユーザーに権限がないことを示します (トークン、ユーザー名、パスワードが間違っています)。

403 禁止 - [*] ユーザーは許可されていますが (401 エラーとは対照的に)、アクセスは禁止されていることを示します。

404 NOT FOUND - [*]: ユーザーが発行したリクエストは存在しないレコードに対するもので、サーバーは操作を実行しませんでした。操作は冪等です。

406 受け入れられません - [GET]: ユーザーが要求した形式は利用できません (たとえば、ユーザーは JSON 形式を要求しましたが、XML 形式のみでした)。

410 Gone -[GET]: ユーザーが要求したリソースは完全に削除され、再度取得することはできません。

422 処理できないエンティティ - [POST/PUT/PATCH] オブジェクトの作成中に検証エラーが発生しました。

500 内部サーバー エラー - [*]: サーバー エラーが発生したため、ユーザーはリクエストが成功したかどうかを判断できません。

エラー処理

ステータス コードが 4xx の場合、エラー メッセージが返され、error がキーとして使用されます。

{
    error: "Invalid API key"
}

結果を返す

さまざまな操作の場合、サーバーからユーザーに返される結果は、次の仕様に準拠する必要があります

GET /collection:リソース オブジェクトのリストを返します (配列)

GET /collection/resource: 単一のリソース オブジェクトを返します

POST /collection: 新しく生成されたリソース オブジェクトを返します

PUT / collection/resource: 完全なリソース オブジェクトを返します

PATCH /collection/resource: 完全なリソース オブジェクトを返します

DELETE /collection/resource: 空のドキュメントを返します

{
    "status": 0,
    "msg": "ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "location":{
                "lat":31.415354,
                "lng":121.357339
            },
            "address":"月罗路2380号",
            "province":"上海市",
            "city":"上海市",
            "area":"宝山区",
            "street_id":"339ed41ae1d6dc320a5cb37c",
            "telephone":"(021)56761006",
            "detail":1,
            "uid":"339ed41ae1d6dc320a5cb37c"
        }
        ...
        ]
}

ハイパーメディア API

RESTful API は、ハイパーメディアとして実装するのが最適です。つまり、返された結果に他の API メソッドへのリンクが提供されるため、ユーザーはドキュメントを確認せずに次に何をすべきかを知ることができます。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

PHP 関連の知識の詳細については、PHP 中国語 Web サイト をご覧ください。

以上がWeb APIインターフェースとRestful仕様の詳細な説明の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。