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

1. すべてのリクエストは POST メソッドを使用します

• get のクエリ文字列と比較して、post を使用すると、複雑なタイプのリクエスト パラメータをサポートできます。たとえば、毎日のプロジェクトでは、get リクエストのパラメーターは配列型です。

• リクエストとレスポンスの統一された署名、暗号化、およびログ処理を促進する

2. URL ルール

• URL には英語のみを含めることができます。英語の単語または略語を使用してください。中国語のピンインは使用しないでください。

• すべての文字に小文字を使用する

• 複数の単語をハイフンで区切ります-。たとえばthird-login、使用しないでくださいthirdlogin。thirdLoginthird_login

• URL のパス部分は、次のような形式系统/模块/操作を使用します。ims/video/list

  • このインターフェイスがマイクロサービスのどのサービスであるかを示すシステム。略語を使用できます
  • システムのサブモジュールを表すモジュール。モジュール名は名詞のフルネームを使用し、単数形を使用します
  • 特定のインターフェースを表す操作は、動詞＋名詞の形をとっており、単数形と複数形を考慮する必要があります。たとえばadd-user、list-users_delete-users

3. HTTP ヘッダー

• ビジネスに依存しない特定のデータを HTTP ヘッダーに入れる
• バックエンド システムは、リクエストとレスポンスの本文を使用せずに、いくつかの一般的なロジックを処理できます。

4. リクエストとレスポンスの本文

• utf-8エンコーディングを使用する
• JSON 形式
• 暗号化が必要な場合は、通常の JSON を暗号化して base64 でエンコードできます

5. HTTP ステータス コード

• 業務の処理結果はhttpステータスコードには反映されず、レスポンスボディのエラーコードフィールドで表されます
• 一部の http ステータス コードのみが、ビジネスに依存しない応答を示します。
  • 200: ビジネスは処理されましたが、処理の成否はレスポンスボディで示されます
  • 400: 間違ったリクエストです。主にリクエスト パラメータの検証で使用されます。クライアントの開発では、正しい形式のリクエストがサーバーに送信されるようにする必要があります
  • 401: 認証に失敗しました。通常、トークンがないか、期限切れのトークンがありません
  • 403: このインターフェースを呼び出す権限がありません。クライアントは、ユーザーがアクセス許可を持っていない操作を非表示にする必要があります
  • 500: サーバー例外

6. フィールドの命名

• JSON は JavaScript 言語に由来するため、フィールドの命名は JavaScript 言語に従い、lowerCamelCase小さな
• 下線付きのリンクは使用しないでくださいsnake_case

7. データ型

共通データ型マッピング

• bool: 文字列にマッピングされます。Y を使用して true を表し、N を使用して false を表します
• int: 数値にマッピング
• long: 文字列にマッピングされます.js の数値型では十分な範囲の値を処理できないため、実際のプロジェクトではさまざまな奇妙な問題が発生します。
• float、double、decimal: 文字列にマッピング
• 日付、時刻: 文字列にマッピング

知らせ：

• IDの概念を表すフィールド、一様に文字列を使用
• データ送信中に特定のフィールドが空の場合、このフィールドを直接省略してネットワークのオーバーヘッドを削減します
• 応答本文のビジネス データに複数のデータ構造が含まれる場合は、以下のユーザーが作成したメッセージのように、ネストされた形式が優先されます。

 "item": {
      "num_iid": "520813250866",
      "title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮",
      "desc_short": "",
      "price": 25.8,
      "total_price": 0,
      "suggestive_price": 0,
      "orginal_price": "25.80",
      "nick": "欢乐购客栈",
      "num": "832",
      "min_num": 0,
      "detail_url": "http://item.taobao.com/item.htm?id=520813250866",
      "pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg",
      "brand": "三刃木",
      "brandId": "4036703",
      "rootCatId": "50013886",
      "cid": "50014822",
      "favcount": "4824",
      "fanscount": "1469",
      "crumbs": [],
      "created_time": "",
      "modified_time": "",
      "delist_time": "",

8. レスポンスボディのフォーマット

• code 業務処理のエラーコードは、大文字を使用し、単語を区切るためにアンダースコアを使用して、エラーの種類を反映できる短い英単語で表されます。数値を使用してエラー コードを表すことはお勧めできません。数値を使用してエラー コード テーブルを表すには、追加のメンテナンスが必要です。