Restful API

• 基础是URI，所有的操作都是基于资源的，不同http action对应资源的不同操作
• url上不能有动词（如login），都要是名词加参数
• GET列表这种情况下，单词要用复数
• ID放在url中，不用放到参数中
• 所有操作都要设计成是无状态的
• 通常可以使用Linux上面的curl、Windows上的curl（要另外安装）和Postman来进行接口的测试。或者使用接口服务提供的Swagger-ui。
  • curl可以使用-H -X --data等指定头部、method、数据
  • curl可以使用-F参数指定文件上传
  • 再加一个-v参数可以看到一些详细信息
• 比较特别的是登陆/退出，因为貌似这两个接口动作没有资源。这时候要转变一下思路，这里的资源其实是授权（authorization），POST是登陆，DELETE是退出。
  • 设计接口时，如果觉得对当前资源进行增删改查都不合适，那么就要重新考虑操作的资源到底是谁
  • 可以用/token，根据能不能获取token来判断是否登录成功
• 传参
  • 各种方法都可以使用path（url中的地址部分）、query（url中的参数部分）两个地方来传参
  • Put、Post等还可以使用body来传参
• URL
  • 编码
    • 为避免非法字符，常先要URLEncode
  • 多级子路径
    • 常用于操作多级路径/多级属性的情况
• Method
  • GET
  • POST
    • 常用于新增数据
    • 不幂等
  • PUT
    • 常用于更新数据，比如更改一部分属性
    • 幂等
    • 整体更新（相当于replace），整个数据都要传，没改的部分也要传
  • PATCH
    • 局部更新，只需要传修改的部分
    • 幂等
• Open API
  • OpenAPI 规范(OAS)定义了一个标准的、语言无关的 RESTful API 接口规范
  • 某些平台的swagger页面支持导出open api格式的接口文档/描述
• 资源版本
  • 一般通过If-Match + eTag的组合来标识资源的版本
  • 有时服务端会要求请求中通过头部的If-Match指定正确的版本，才允许更新/覆盖旧的资源
• API版本
  • 只能把请求的接口的版本放到URL或者Request Header中
  • URL（直观，容易理解，但有点违反rest的原则）
    • 可以通过部署来解决，比如通过Nginx使用不同的域名或不同的前缀（比如.../v1/...），导向不同的服务或者说接口
    • 修改application.yml中的contextPath：server.servlet.contextPath: /tutorial-v2，即部署不同的spring-boot微服务，只是配置不同，使用不同的端口，然后Nginx中配置导向不同的spring-boot微服务
    • 修改@RequestMapping中的参数，比如@RequestMapping("/v1/tvseries")
    • 增加request的参数，比如/tvseries?version=2，然后服务端简单的做相应修改，可以在spring的controller中修改注解，比如@GetMapping(value="/{id}", params="version=2")
  • Request Header（缺点是一些缓存服务器只管url，所以可能导致乱掉）
    • 自定义request header，比如Version: 2，可以在服务端使用@GetMapping(value="/{id}", headers="Version=1")注解来对应上接口
    • 使用Accept（即使用标准的http header），比如Accept: application/vnd.xxx.v2+json，也算是一个标准的http头，可以在服务端使用@GetMapping(value="/{id}", produces="application/vnd.xxx.v2+json")注解来对应上接口
  • 自定义ApiVersion注解（RequestMappingHandlerMapping）
    • 使用@ApiVersion注解，但是需要自定义一个继承自RequestMappingHandlerMapping的类，然后自己实现把request分配到某个方法的规则（比如根据方法名、注解等信息），实现比较麻烦，适用于版本复杂的情况，需要实现
  • 分类
    • Major Version
      • A major version update indicates breaking changes in an API. The major version of an API is part of the URL path of XXX for calling a service API.
      • A change is considered as breaking, if the behavior of an existing documented API feature is changed in a way such that clients using that feature might not work anymore. To be able to work with the updated version, the clients need to be modified. Breaking changes are, e.g.:
        • Removing, renaming, or moving API entities such as:
          • endpoints
          • HTTP methods associated with endpoints
          • operation query, body, or header parameters
          • schema properties
          • authorization roles
        • Changing the way how existing features need to be used, e.g., by introducing new preconditions to be fulfilled
        • Changing an already present workflow
        • Making optional parameters or schema properties mandatory
        • Changing documented functional or non-functional behavior in significant ways
      • A major version update resets the minor and patch version values to zero initially. For example, in case an API with version v3.1.2 undergoes a major update, the version value is changed to v4.0.0.
    • Minor Version
      • A minor update indicates backwards compatible changes in an API. Clients that are compatible with XXX minor update rules will continue to work with the updated API version.
      • A change is considered as backwards compatible, if optional new features are added to an API. For example, adding optional API entities such as the ones mentioned above for breaking changes. A client is considered compatible with XXX minor update rules if it tolerates new API entities, e.g., new optional schema properties or new error responses.
      • A minor version update resets the patch version values to zero. For example, in case an API with version v3.1.2 undergoes a minor update, the version value is changed to v3.2.0.
    • Patch Version
      • A patch version udpate only relates to the API specification document. The implementation remains unchanged. Patch updates are corrections or improvements of descriptions or examples in the API specification. Patch updates might also fix a mismatch between specification and actual implementation of an API. The latter case is particularly important for client developers, who want to develop compatible clients.
• 目前有流行的成熟的接口定义规范，如Open API 3.0