Web APIインターフェース設計仕様

プロトコル

APIとクライアントの通信プロトコルには主にhttpとhttpsがありますが、インタラクティブなデータ通信の安全性を確保するためにhttpsの使用を推奨します。

ドメイン名

主に 2 つの形式が含まれます:
メインドメイン名: https://api.example.com
サブディレクトリ: https://example.org/api/

バージョン管理

バージョン管理は主に、アプリ、WeChat アプレット、ソフトウェアクライアントなどで使用され、古いバージョンとの互換性が必要なシナリオに合わせてシステムを同時にリアルタイムで更新できない場合に使用されます。
複数のバージョンを採用して共存し、段階的にリリースする。
バージョン番号: v{n} n はバージョン番号を表し、整数型と浮動小数点
型に分けられます整数型: 大機能バージョンのリリース形式; すべての API インターフェイスが現在のバージョン状態にあります (例: v1、v2) .
浮動小数点型: 小さいバージョン番号であり、API を補足する機能のみを持ちます。他の API はデフォルトで大きいバージョン番号に対応する API を呼び出します。例: v1.1 v2.2

URL にバージョン番号を入力します:
https://api.example.com/v{n}/
この方法はより便利で直感的であり、バージョン番号は主に整数です。

リクエストヘッダー (リクエストヘッダー) にバージョン番号を入力します。

headers:{
    
    
    version: 'v{n}'
    ...
}

バージョン番号には整数、浮動小数点などが使用できます。

パスのルール

パスは「エンドポイント」とも呼ばれ、API の特定の URL を表します。。
RESTful アーキテクチャでは、各 URL がリソースを表すため、URL には動詞を含めることはできません。名詞のみを含めます。多くの場合、使用される名詞はデータベースのテーブル名に対応します。。一般に、データベース内のテーブルは同じ種類のレコードの「コレクション」であるため、API 内の名詞も複数形にする必要があります。

たとえば、さまざまな動物や従業員の情報を含む動物園の情報を提供する API がある場合、そのパスは次のように設計する必要があります。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

リクエスト方法

リソースの特定の操作タイプは、HTTP 動詞によって表されます。
一般的に使用される HTTP 動詞は 4 つあります (括弧内は対応する SQL コマンドです)。

GET（SELECT） //从服务器取出资源（一项或多项）。
POST（CREATE）//在服务器新建一个资源。
PUT（UPDATE） //在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）//从服务器删除资源。

例えば：

GET /product   //列出所有商品
POST /product  //新建一个商品
GET /product/ID //获取某个指定商品的信息
PUT /product/ID //更新某个指定商品的信息
DELETE /product/ID //删除某个商品
GET /product/ID/purchase //列出某个指定商品的所有投资者
GET /product/ID/purchase/ID //获取某个指定商品的指定投资者信息

パラメータを渡す

受信パラメータは 3 つのタイプに分類されます。

アドレスバーパラメータ

restful 地址栏参数 /api/v1/product/122 
// 122 为产品编号，获取产品为 122 的信息

取得モードのクエリ文字列。このメソッドは主に、次のようにクエリをフィルタリングするために使用されます。

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

ボディデータのリクエスト
は主に新規データの提出などに使用されます。
リクエストヘッダーは、リクエストの形式情報、バージョン番号、トークンキー、言語、その他の情報を
格納するために使用されます。

{
    
    
    Accept: 'application/json',     //json格式
    version: 'v1.0'                       //版本号
    Authorization: 'Bearer {access_token}',   //认证token
    language: 'zh'                      //语言
}

戻り値の形式

デフォルトの戻り形式:

{
    
    
    errorCode: 0,                    //状态码
    message: 'ok',                   //提示信息
    data: {
    
    }                         //主体数据
}

応答形式として json 形式を使用すると、ステータスコードは次の 2 種類に分けられます。

statusCode: システムステータスコード。応答ステータスの処理に使用され、http ステータスコードと一致します。たとえば、200 はリクエストが成功したことを意味し、500 はサーバーエラーを意味します。
コード: ビジネスステータスコード。ビジネスステータスの処理に使用されます。通常、0 は正常を示します。必要に応じてエラーコード比較テーブルを設計できます。次の WeChat の公式ドキュメントを参照してください: https:
//developers.weixin.qq .com/doc/offiaccount/Getting_Started /Global_Return_Code.html
さまざまな状況に応じて、メッセージプロンプト情報を統一する必要がある
データは、ビジネス要件に応じて、JSON オブジェクトまたは JSON 配列にすることができます。ただし、さまざまな状況下でもデータ型が一貫していることを確認してください。
通常のバックエンドインターフェイスの応答、HTTP ステータスコードはデフォルトで 200 を返します。インターフェイスは次の状況でのみ 200 以外で表示されます: サーバー認証が失敗した場合、
HTTP ステータスコード 401 が返されます。
サードパーティソフトウェアによって返される標準エラーコードたとえば、Nginx によって返される 5** エラーコード
インターフェイスの HTTP ステータスコードが 200 ではない場合、返される構造は次のとおりです。

{
    
    
    "errorCode": {
    
    通用处理结果代码},
    "data": null,
    "message": "对应的错误消息"
}

配列の形式は次のとおりです

{
    
    
    "code": 0,
    "message": "SUCCESS",
    "data": [
            {
    
    
                "id":1,
                "name":"小王",
                "age":20
            },
            {
    
    
                "id": 2,
                "name": "小李",
                "age": 30
            }
        ]
}

{
    
    
    "code": 0,
    "message": "SUCCESS",
    "data": [
        "小李",
        "小王"
    ]
}

ページ分割されたリスト形式

{
    
    
    "code": 0,
    "message": "SUCCESS",
    "data": {
    
    
        "pageSize": 10,
        "page": 12,
        "total": 118,
        "list": [
            {
    
    
                "id": 1,
                "name": "小王",
                "age": 10
            },
            {
    
    
                "id": 1,
                "name": "小王",
                "age": 10
            }
        ]
    }
}