RESTfulAPI接口设计规范与快速入门

# 方式1.独立域名(推荐)
https://api.weiyigeek.top

# 方式2.主域名后的目录
https://weiyigeek.top/api/

# 方法1.将API的版本号以及该api应用的应用程序名称放入URL(推荐)
http://api.weiyigeek.top/app/1.0/foo 
http://api.weiyigeek.top/app/1.1/foo 
 
# 方法2：将版本号放在HTTP头信息中，但不如放入URL方便和直观,Github采用这种做法。
# 因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URL。
# 版本号可以在HTTP请求头信息的Accept字段中进行区分（参见Versioning REST Services）：
Accept: app.weiyigeek-top.foo+json; version=1.0 
Accept: app.weiyigeek-top.foo+json; version=2.0

# 获取所有产品清单 
GET /products 
# 获取产品4的信息 
GET /products/4 
# 更新产品4的信息 
PATCH（或）PUT /products/4
# 新建产品 
POST /products 

#-------------------------------#
# 错误或者不建议的示例
# 获取所有端口 
/getProducts 
# 获取所有订单 
/listOrders 
# 订单1的所有回复（排序返回） 
/retreiveClientByOrder?orderId=1

# 获取单个产品 
GET http://api.weiyigeek.top/AppName/1.0/products/1 
# 获取所有产品 
GET http://api.weiyigeek.top/AppName/1.0/products

GET（SELECT）：从服务器取出资源（一项或多项）。 
POST（CREATE）：在服务器新建一个资源。 
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。 
DELETE（DELETE）：从服务器删除资源。
PATCH（UPDATE）：在服务器更新(更新)资源（客户端提供改变的属性）。 
HEAD：获取资源的元数据。 
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

# 获取所有产品 
GET http://api.weiyigeek.top/AppName/1.0/products
# 创建单个产品 
POST http://api.weiyigeek.top/AppName/1.0/products
# 更新单个产品 
PUT http://api.weiyigeek.top/AppName/1.0/products/1 
# 删除单个产品 
DELETE http://api.weiyigeek.top/AppName/1.0/products/1 

# 当然为了安全你也可以只使用GET（查询操作）与POST请求(关键性操作)，例如
# 更新产品ID为1的数据
POST http://api.weiyigeek.top/AppName/1.0/products/1/update
# 删除产品ID为2的数据
POST http://api.weiyigeek.top/AppName/1.0/products/1/delete

# 指定返回记录的数量 
GET http://api.weiyigeek.top/AppName/1.0/products?limit=10
# 指定返回记录的开始位置
GET http://api.weiyigeek.top/AppName/1.0/products?offset=10
# 指定第几页以及每页的记录数
GET http://api.weiyigeek.top/AppName/1.0/products?page=2&per_page=100
# 指定返回结果按照哪个属性排序以及排序顺序
GET http://api.weiyigeek.top/AppName/1.0/products?sortby=name&order=asc
# 指定筛选条件
GET http://api.weiyigeek.top/AppName/1.0/products?animal_type_id=1

# 参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。
比如，GET /zoos/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

// # 正常返回
{ 
  "code": 200, 
  "message": "服务器成功返回用户请求的数据.",
  "data": {
    "name": "WeiyiGeek",
    "blog": "blog.weiyigeek.top"
  } 
}

// # 异常返回
{ 
  "code": 0, 
  "message": "服务器未能成功返回用户请求的数据.",
  "data": {} 
}

{ 
  "code": 10002, 
  "message": "User data operation completed.",
  "data": {} 
}

{ 
  "code": 20002, 
  "error": "The server failed to successfully return the data requested by the user." 
}

# Linux
mkdir -vp ./config/{tls,conf} ./docs/swagger ./handler/sd/user ./model ./pkg/{errno,version} ./router/middleware ./service ./util ./vendor

# windows
mkdir -vp ./config/tls ./config/conf ./docs/swagger ./handler/sd/user ./model ./pkg/errno ./pkg/version ./router/middleware ./service ./util ./vendor