HTTP API Interface Design Specification

1. All requests use the POST method

• Compared with the query string of get, using post can support complex types of request parameters. For example, in daily projects, the get request parameter is an array type.

• Facilitate unified signature, encryption, and log processing of requests and responses

2. URL rules

• The URL can only contain English, use English words or abbreviations, do not use Chinese pinyin

• Use lowercase letters for all characters

• Separate multiple words with a hyphen -, such as third-login, do not use thirdlogin, thirdLoginorthird_login

• The path part of the URL 系统/模块/操作uses the format, such asims/video/list

  • System, indicating which service in the microservice this interface is, you can use the abbreviation
  • Modules, which represent submodules of the system. The module name uses the full name of the noun and uses the singular form
  • Operation, which represents a specific interface, uses the form of verb + noun, and needs to consider singular and plural. For example add-user,list-usersdelete-users

3. HTTP header

• Put specific business-independent data in HTTP headers
• The backend system can handle some common logic without involving the request and response body

4. Request and Response Body

• use utf-8encoding
• JSON format
• If encryption is required, normal JSON can be encrypted and encoded with base64

5. HTTP status code

• The processing result of the business is not reflected in the http status code, but is represented by the error code field of the response body
• Only some http status codes indicate business-independent responses, such as
  • 200: The business has been processed, but the success or failure of the processing is indicated by the response body
  • 400: Wrong request, mostly used in request parameter verification. Client development must ensure that the correct format of the request is submitted to the server
  • 401: Authentication failed, generally there is no token or no token expires
  • 403: No permission to call this interface. The client should hide operations that the user does not have permission for
  • 500: server exception

6. Field Naming

• JSON comes from the javascript language, so the field naming follows the javascript language, using lowerCamelCasethe small camel spelling
• Do not use underlined linkssnake_case

7. Data Types

Common Data Type Mapping

• bool: mapped to string, use Y to represent true, N to represent false
• int: mapped to number
• long: mapped to string, because the number type of js can not handle enough range of values, it will lead to various strange problems in actual projects
• float, double, decimal: mapped to string
• Date, time: mapped to string

Notice:

• The field representing the concept of ID, uniformly use string
• During data transmission, if a certain field is empty, omit this field directly to reduce network overhead
• When the response body business data contains multiple data structures, the nested format is preferred, such as the message created by the user below

 "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. Response body format

• code The error code of business processing is represented by short English words that can reflect the type of error, using uppercase letters, and using underscores to separate words. It is not recommended to use numbers to represent error codes, and to use numbers to represent error code tables requires additional maintenance.