设计优美的Web API:

易于使用、便于更改、健壮性好、不怕公开

REST的两层含义:

  • 指符合Fielding的REST架构风格的Web服务系统
  • 指使用符合RPC风格的XML或JSON + HTTP接口的系统(不使用SOAP)

端点的基本设计:

  • 短小便于输入的URI-
  • 人可以读懂的URI
  • 没有大小写混用的URI
  • 修改方便的URI
  • 不暴露服务端架构的URI
  • 规则统一的URI

HTTP方法和端点:

  • GET获取资源
  • POST新增资源
  • PUT更新已有资源
  • DELETE删除资源
  • PATCH更新部分资源

查询参数和路径的使用区别

  • 表示唯一资源时,放在路径中
  • 当参数可以忽略时,放在查询参数中

    RESTful的设计级别

  • 使用HTTP
  • 引入资源的概念
  • 引入HTTP动词
  • 引入HATEOAS

    如何指定数据格式?

  • 查询参数:url?format=xml
  • 扩展名:/url.json
  • Accept头部字段

    让用户决定响应的内容

  • GraphQL

    通过状态码表示错误信息

    1xx:消息
    2xx:成功
    3xx:重定向
    4xx:客户端原因造成的错误
    5xx:服务端原因造成的错误

    缓存与HTTP协议规范

    RFC7234:过期模型/验证模型
    过期模型:Cache-Control/Expires
    验证模型:Last-Modified/ETag
    Vary首部:指定缓存单位
    Conent-Type/Accept:指定媒体类型

API版本控制

  • 在URI中嵌入版本号
  • 在查询字符串中加入版本信息
  • 通过媒体类型指定版本

    API安全问题

  • 推荐使用HTTPS
  • XSS/XSRF注入漏洞
  • 返回正确的数据格式
  • 使用安全相关首部
  • 采用KVS实现访问限制

    提供API文档

  • API Blueprint
  • API Console/Apigee
  • 提供SDK