第一章 总则

  • 本标准定义了在做接口设计时，需要遵守的基本约束。

    第二章 术语

  • RESTful : REST(Representational state transfer)是Roy Fielding在2000年提出的一种架构风格。 RESTful风格API是符合该架构的一种API设计风格。

  • HATEOAS : 全称是Hypertext As The Engine Of Application State，是REST架构的一种约束，通过在返回值中带有操作资源的链接信息，进一步将客户端和服务器解耦。

  • Richardson成熟度模型: 根据REST的约束对API进行评级的一种方法，分为四级（Level0到Level3）:

    • Level 0 : 仅将HTTP（或其它协议）当成传输方式，实际上只是RPC的一种方式，没有资源的概念。
    • Level 1 : 引入了资源的概念，不过通常只用到GET或POST，而且可能将二者等价使用。
    • Level 2 : 使用HTTP的方法（POST , DELETE , PUT , GET）来代表资源的增删改查，并使用HTTP状态码来代表不同的结果。
    • Level 3 : 使用HATEOAS方式，在资源的返回值中包含操作资源的链接信息。

      第三章 接口设计原则

  • 接口设计采用RESTful Level 2模型，不反对采用Level 3模型。

  • 接口需要带版本号。
  • 接口需要有文档。
  • 接口需要做认证。

  • 接口需要无状态，不能依赖于会话（session）。

    第四章 接口设计细则

    4.1 URL格式

    接口URL定义中，需要将接口请求的数据抽象为资源，接口即是对资源的增加、删除、修改（覆盖或部分修改）、查询。

    4.1.1 资源名

  • 中文名称的资源采用单数，英文名称的资源采用复数。

    /aj/{id} // 某个ID的案件 /msaj/{id} //某个ID的民事案件 /msaj/{ajid}/dsr //某ID的民事案件的所有当事人 /msaj/{ajid}/dsr?ssdw=1 //某ID的民事案件下诉讼地位为1的当事人 /writs/{id} //某ID的文书 /users/{id} //某ID的用户

  • 不要在资源上加上动词描述,比如：

    /addUser /deleteUser /modifyUser /queryUser

  • 特殊情况需要指定行为的，在行为前面加上统一的actions关键字，例如：

    /msaj/{ajid}/actions/fen_an //对某个案件进行分案

  • 两个词之间采用_做为连接符。

    4.1.2 采用HTTP method

  • GET
    GET方法代表读取，其请求是幂等的，不能修改资源的信息。
    注意：
    如果对于一个参数超长的get请求，可采用post请求，并在在header中加上X-HTTP-Method-Override:get。Controller层仍是以get来处理。get请求不允许直接带请求体，因为部分框架不支持。

  • DELETE
    DELETE方法代表删除该资源。删除成功后返回状态码204，不返回数据。可带请求体。
  • POST
    POST方法代表创建资源。创建成功后返回状态码201，并返回该资源给调用方。可带请求体。
  • PUT
    PUT方法代表覆盖资源。更新成功后返回状态码204，无响应体返回。可带请求体。
  • PATCH
    PATCH方法代表修改部分资源。更新成功后返回状态码204，无响应体返回。可带请求体。推荐用patch方法，大部分应用场景下，更新都只是更新部分数据。

注意：
建议url长度不要超过1024，浏览器、某些js框架、nginx等，都可能对url长度进行限制。

4.1.3 版本信息

所有接口必须带版本信息，版本信息放URL中，而不是在header中。
推荐格式：/api/v1/资源名称/{id}。

4.1.4 统一前缀

推荐接口都以/api开头，便于统一处理。

4.1.5 分页及排序

  • 在URL中增加offset和limit参数用于分页。

  • 在URL中增加sort参数用于排序，默认正序，带-表示倒序。比如：

    /api/v1/users?sort=-fyid,create_time 代表fyid倒序，create_time正序。

  • 返回的分页数据中，在响应全中，包含如下元素：

    • offset (和请求值一样)
    • limit (和请求值一样)
    • total（能查出的总记录数）,注：total非必须，可以不传，以提高性能。
    • data（此次分页的数据）

      4.2 请求头（Request headers）

  • 带有Bearer 认证信息：
    Authorization: Bearer <token>
    推荐采用JWT token。

    4.3 请求体(Request body)

  • 文件上传采用multipart/form-data格式。

  • 其它请求均采用application/json格式，不得使用application/x-www-form-urlencoded。

    4.4 响应状态码（Response status）

    如无必要，勿增实体。凡是HTTP Response Status能表述的，均使用HTTP的响应状态码。

    2XX

  • 200 : 请求成功，响应体中带有资源的数据。

  • 201 : 资源创建成功。
  • 202 : 请求已接收。对于耗时较长的需要后台异步处理的，服务在接收请求后，返回202。

  • 204 : 响应中无内容。通常是在执行PUT、POST、DELETE后，不返回资源的内容。

    3XX

  • 301 : 如果接口废弃，迁移到新接口中，可以返回301重定向。

  • 304 : 资源未修改。和204一样，在响应体中不会带有内容，其区别在于如果针对请求头中的If-Modified-Since或者If-None-Match指定的版本，资源没有修改，则返回304。

    4XX

  • 400 ： 错误请求。通用的客户端错误状态码。通常是由于参数不正确。

  • 401 ： 未授权。客户端未能提供有效的认证信息。
  • 403 ： 请求被拒绝。客户端已经认证成功，但是无权访问该资源。
  • 404 ： 资源不存在。
  • 410 ： 如果接口永久废弃不用，可返回410。请慎用。

  • 429 ： 请求次数超限。

    5XX

  • 500 ： 服务器内部错误。

    4.5 响应头（Response headers）

    Content-Type需要与数据保持一致，POJO类的数据统一采用application/json;charset=UTF-8做Content-Type。

    4.6 响应体（Response body）

  1. 除文件下载外，响应体均采用JSON格式，JSON不要进行格式化。针对4XX错误和5XX错误，需要提供有供的信息，格式如下：

    1. {
    2. "code":"",
    3. "message":""
    4. }

    Copy
    code是业务系统针对响应状态码细化的业务错误码，不做统一约束,可以为空。
    message是针对该错误的描述信息，不能为空。

  2. 响应体的VO，应该同时带有带有代码值和代码文本。
    如单值代码、多值代码、组织机构、案由。
    对于外键引用的数据不做要求，根据业务自行设计。

    4.7 认证