Skip to content

接口设计

Jump to bottom
kext edited this page Sep 27, 2017 · 1 revision

API以restful风格对外提供服务

HTTP 方法使用

具体接口介绍文档必须写清楚所使用的方法

  • GET 获取信息
  • POST 新建资源
  • PUT 更新资源
  • DELETE 删除资源
  • HEAD 检索资源是否存在

登录接口 登录接口必须使用POST方法，Content-Type 支持 application/json 、multipart/form-data ，post 提交的用户数据使用 json 格式

curl -X POST -H "Content-Type: multipart/form-data"   -d '{"mobile":"13553641342","password":"admin1"}' "http://localhost:8080/api/base/authenticate"

当然密码要传密文

需要登录的接口

需要登录的接口需要在header中带上Authorization参数例如

curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJKZXJzZXktU2VjdXJpdHktQmFzaWMiLCJzdWIiOiJiaW5nbGluIzIwMDAwIiwiYXVkIjoidXNlciIsImV4cCI6MTQ3NjI3MzU4MSwiaWF0IjoxNDc2MjY2MzgxLCJqdGkiOiIxIn0.qFhBXQaEocjdsUpMiR2kBRPyzx5u3Dl6L8gTw-NW5oM" "http://localhost:8080/users/bean"

注意：Bearer后面有一个空格

使用缓存

使用缓存时在header中加入 If-None-Match 头部，值为上一次调用时获得的Etag值

curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJKZXJzZXktU2VjdXJpdHktQmFzaWMiLCJzdWIiOiJiaW5nbGluIzIwMDAwIiwiYXVkIjoidXNlciIsImV4cCI6MTQ3NjI3MzU4MSwiaWF0IjoxNDc2MjY2MzgxLCJqdGkiOiIxIn0.qFhBXQaEocjdsUpMiR2kBRPyzx5u3Dl6L8gTw-NW5oM" -H "If-None-Match: 69a87434fce35f0f1fa900e7b87cd97a" "http://localhost:8080/users/bean"

注意：Etag值为上一次调用时服务端响应header的Etag值

客户端信息参数

客户端信息统一放到User-Agent 请求头中，用分号隔开每个属性，例如

curl -X GET -H "X-User-Agent: ver=30;caller=app;ch=guangwang;mac=02:00:00:00:00:00;os=23|Lenovo K50-t5;platform=android" "http://localhost:8080/users/bean"

请求id

为了快速定位问题和排查bug，需要在每一个请求中附带一个唯一id，为了保证唯一，统一使用 UUID，我们将在请求和响应中加入Request-Id头部，例如,

curl -X GET -H "Request-Id: fe0082bb-03be-400f-aa1a-ba49dd8caf27" "http://localhost:8080/users/bean"

排序和分页

分页排序 排序信息放在Range的header中格式是"Range:sort=name,order=desc;sort=age,order=asc;page=0,size=10"，page从0开始，默认page为0，size为10。如果有需求需要修改排序规则的，服务端可能会忽略客户端发送的这个header 版本信息 对于相同的接口可能有不同的版本，这是需要在header中指定版本号，默认是v1。默认不要传这个参数过来

curl -X GET -H "Version:v1" "http://localhost:8080/users/bean"

异常处理

当服务端发生异常时，http code 为 500 ，返回如下json 字符串: {"msg":"error reason","code":"500 或者是具体的业务代码"}

服务端响应

  • 状态码 说明
  • 200 OK 正常返回
  • 304 Not Modified 资源没改变，使用etag时候
  • 400 Bad Request 错误请求
  • 401 Unauthorized 未授权
  • 403 Forbidden 除非拥有授权否则服务器拒绝提供所请求的资源
  • 404 Not Found 资源未找到
  • 405 Method Not Allowed 指出请求方法(GET, POST, HEAD, PUT, DELETE, 等)对某些特定的资源不允许使用。
  • 406 Not Acceptable 请求资源的MIME类型与客户端中Accept头信息中指定的类型不一致
  • 412 Precondition Failed 请求头信息中的某些先决条件是错误的，这里具体指请求头的缺少Request-Id，或者sign错误
  • 415 Unsupported Media Type 请求所带的附件的格式类型服务器不知道如何处理
  • 429 Too Many Requests 请求太频繁
  • 500 Internal Server Error 内部服务器错误
Clone this wiki locally