specification

api interface must be added to the version number, the initial version of [v1], multiple versions may also api version online
Do not use the rest PUT and DELETE, because many browsers do not support a lot of the framework does not support
POST when you need to transfer large amounts of data using the remaining use GET on it;

Here GET and POST no clear meaning, GET can add
All paths path all lowercase, separated by an underscore, all parameters, including the inside of the POST body, and the use of header hump. For example: http://127.0.0.1/v1/wechat/mch_info/list_mch_info?page=2&perPage=100
We return to the normal use unified format json return
Use Token Token to do the user's identity verification and classification authority
Exposed to external requests must use SSL

Path specific implementation

path = / {version} / {specific business functions} / {table} / {behavior}

{Version}: at the beginning of all V1,
} {Specific business functions:
- App of the setting, a database named app_setting, then the specific business function = setting
- wechat architecture group, the database named arch_wechat, then the specific business function = wechat
{} Table: table data is
} {Behavior: general is the method name
? Limit = 10: Specifies the number of records returned
? Offset = 10: Returns the specified record start position.
? Page = 2 & perPage = 100: specify the number of records per page, and the first few pages.
? SortBy = name & order = asc: Specifies the returned result sorting, and sort order according to which property.

http protocol	method	Behavior path	Explanation
POST	add (POJO)	/add	Add an object, receiving information json
GET	insert(param …)	/insert?param1=?&param1=?	Insert an object, the plurality of mode parameters, and add the same effect, but with different parameters pass mode
GET	deleteById(long)	/delete_by_id?id=?	The database is not deleted, but deleted on the business semantics
POST	update (POJO)	/update	Update an object, receiving information json
GET	updateById(long)	/update_by_id?id=?	{} Table has been specifically identified entities, where all can not update_pojo_by_id
GET	getById(long)	/get_by_id?id=?	{} Table has been specifically identified entities, where all can not get_pojo_by_id
GET	listByParam (Object)	/list_by_param?param=?&page=2&perPage=100	a plurality of query list, all of the default, can bring limit, offset, page, sortBy, order parameters

Reference database design
https://blog.csdn.net/zengqiang1/article/details/79338660
[Recommended] named the best table is to add "The role of business name _ the table."
Positive examples: app_user / trade_config
[Recommended] library name and the name of the application as much as possible consistent with business projects {} _ {} function, business projects and how to write reference functions

Request

Request must bring the common parameters without these common parameters, the value may not be filled, but must bring
Public parameters inside the token must be put on, because we based this token, do user login authentication
Public parameters wrote http header inside, key: _head, value json format, directly into the rear end of the object
{
"token": "123", // sso token, must bring, this parameter to verify whether the user is logged in, has confirmed which user
"timestamp": "1234", // send request timestamp
"userId": "123", // sso user the above mentioned id
"channel": "123", // sources, download the package from above which channel (iOS only one App Store, Android millet, application treasure, pea pods and other domestic channels), this must also have a table
"channelCode": "123", // channel identity, self: own channels, other Penguin external sources can also register users, such as business channels mapped to the inquiry: 'sq: qq mobile phone channels, qb: qq browser channels', indicating which channels come from, this must also have a table
"pushId": " 134 ", // if the product or operational needs of our push message to some users, depending on other parameters of the common user grouping, and then give him a push to get pushid message.
"InitStamp": "123", // first installation package timestamp
"device": "123", // device name
"deviceId": "123", // device-unique code
"systemVersion": "123", // APP-specific, platform (Android, iOS) version number
"ComeFrom": "123", // source projects, such as APP to do a Mother's Day event, or 520 activities, from = Mother's Day activities, from = 520 events, activities indicate that I do a conversion, this must also be there is a table
"platformId": "123", // platformId table @see example. 1: Web, 2: the iOS,. 3: the Android,. 4: miniapp
"appName": "123", // appName application name, the control table ,, for example, app: app application, cai: small quiz program
"appVersion": "123", // we own app version number of
"extra": "123" // additional parameters, such as the scene of the follow-up to do when it will ABTesting used, you can also do some extra business needs field, depending on the operational availability
}

Compression format

{"token":"123","timestamp":"1234","userId":"123","channel":"123","channelCode":"123","pushId":"134","initStamp":"123","device":"123","deviceId":"123","systemVersion":"123","come_from":"123","platformId":"123","appName":"123","appVersion":"123","extra":"123"}

The corresponding database field

CREATE TABLE `user_extra_relation` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '自增主键',
  `user_id` bigint(20) DEFAULT NULL COMMENT 'user表中的id',
  `come_from` varchar(64)  NOT NULL DEFAULT '' COMMENT '项目来源，例如APP要做一个母亲节的活动,或者520活动，from=母亲节活动,from=520活动，表明我做活动的一个转化率,这个也必须有一个对照表,
  `device_id` varchar(64)  NOT NULL DEFAULT '' COMMENT '第一次产生用户注册的设备id',
  `channel_code` varchar(32)  NOT NULL DEFAULT 'self' COMMENT '渠道标识，self：自有渠道，其他外部渠道也可以注册用户,非必传，默认 self',
  `platform_id` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '平台ID，platformId 对照表,例如 1:web，2:iOS，3:Android，4:miniApp',
  `app_name` varchar(32)  NOT NULL DEFAULT '' COMMENT 'appName 应用名称,
  `token` varchar(64)  NOT NULL DEFAULT '' COMMENT '用户token',
  `timestamp` varchar(64)  NOT NULL DEFAULT '' COMMENT '发送请求时间戳',
  `channel` varchar(32)  NOT NULL DEFAULT '' COMMENT '渠道来源,从哪个渠道上面下载的包（iOS就只有一个App Store，Android有小米，应用宝，豌豆荚等国内的渠道),这个也必须有一个对照表https://lexiangla.com/docs/27c78dba373e11e8892b5254004fae61',
  `push_id` varchar(64)  NOT NULL DEFAULT '' COMMENT '假如产品或者运营需要我们给部分用户推送消息，可以根据其他公共参数把用户分群，然后拿到pushid给他push消息。',
  `init_stamp` varchar(64)  NOT NULL DEFAULT '' COMMENT '首次安装包时间戳',
  `device` varchar(64)  NOT NULL DEFAULT '' COMMENT '设备名',
  `system_version` varchar(32)  NOT NULL DEFAULT '' COMMENT '系统版本',
  `app_version` varchar(32)  NOT NULL DEFAULT '' COMMENT '我们自己APP的版本号',
  `extra` varchar(128)  NOT NULL DEFAULT '' COMMENT '额外参数，后续做ABTesting等场景的时候会用到，也可以做一些额外的业务需求字段，视各业务而定',
  `is_delete` tinyint(3) unsigned NOT NULL DEFAULT '0' COMMENT '是否删除 0-未删除、1-删除',
  `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_id` (`user_id`)
) ENGINE=InnoDB COMMENT='用户附加信息表，表明用户来源等，第一次产生userId时插入信息到此表'

Response

Using JSON, do not use XML
By default, to support gzip
Unified format:

{
      "code" : 0,
      "msg" : "Something bad happened",
      "data" : {

      }
    }

code: 0 for a successful, non-zero as a failure
msg: When the code is non-zero for errors. When the code is 0, msg generally "success".
data: When the code is 0, get results, all expressed in json manner. When the code is non-0, data no data

Error Handling

Do not directly handle an exception thrown to the client, generally requires a consistent exception handling classes, and exception information in a uniform format to return to the front, a unified format reference directory "Response"

Identity Mapping

Reserved error code, you can customize the error code, error code reference in their entirety

error code description

0 Request successful
Gender-relational mapping

id gender

0 Is not set

1 male

2 Female

error code	description
0	Request successful

id	gender
0	Is not set
1	male
2	Female

platformId description

pLATFORMS	platform
1	web
2	iOS
3	Android
4	miniApp
5	mp micro-channel public number

Description appName

appName Application Name

app XXXapp

jincai Guess applet
channelCode channel identification description, the default is self (own channel), which is derived from the event, add an event, you need to add the appropriate logo here

channelCode Channel logo

self Own channels
userCateGorg user class, the default for customers. The future we will probably have sales, or other

userCateGorg User Category

co client

appName	Application Name
app	XXXapp
jincai	Guess applet

channelCode	Channel logo
self	Own channels

userCateGorg	User Category
co	client

glowd

Published 49 original articles · won praise 31 · views 130 000 +

Private letter concerns

http api design specifications