如何设计API接口

如何设计API接口

一、什么是接口文档？

接口文档是一种说明文档，用于描述系统所提供接口信息。在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发。

二、为什么要写接口文档？

1、能够让前端开发与后台开发人员更好的配合，提高工作效率

2、项目迭代或者项目人员更迭时，方便后期人员查看和维护

3、方便测试人员进行接口测试

三、接口规范是什么？

首先接口分为四部分：接口协议、请求方式、请求路径、请求参数、返回参数

1. 接口协议，如http、https、tcp协议等。

2. RESTful API请求方式:

   1. GET（查询）：从服务器取出资源（一项或多项）。
   2. POST（新增）：在服务器新建一个资源。
   3. PUT（修改）：在服务器更新资源（客户端提供完整资源数据）。
   4. DELETE（删除）：从服务器删除资源。
   5. PATCH（修改）：在服务器更新资源（客户端提供需要修改的资源数据，用的比较少）。

3. 请求路径，接口的url。

   1. URI，Uniform Resource Identifier，统一资源标识符。

   2. URL，Uniform Resource Location，统一资源定位符。

   3. URI 简单来理解就是标识/定义了一个资源，而 URL 在定义/标识资源的同时还需要描述如何访问到该资源。一般来说 URI 有一个通用的结构描述：

      URI = scheme "://" host ":" port "/" path [ "?" query ][ "#" fragment ]

      1. scheme: 指底层用的协议，如http、https、ftp
      2. host: 服务器的IP地址或者域名
      3. port: 端口，http默认为80端口
      4. path: 访问资源的路径，就是各种web 框架中定义的route路由
      5. query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
      6. fragment: 锚点，定位到页面的资源，锚点为资源id

   4. 我们在设计API时URL的path是需要认真考虑的，而RESTful对path的设计做了一些规范，通常一个RESTful API的path组成如下：

      /{version}/{resources}/{resource_id}

      1. version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。
      2. resources：资源，RESTful API推荐用小写英文单词的复数形式。
      3. resource_id：资源的id，访问或操作该资源。

4. 从大体样式了解URL路径组成之后，对于RESTful API的URL具体设计的规范如下：

   1. 不用大写字母，所有单词使用英文且小写。
   2. 连字符用中杠"-"而不用下杠"_"
   3. 正确使用 "/"表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
   4. 结尾不要包含正斜杠分隔符"/"
   5. URL中不出现动词，用请求方式表示动作
   6. 资源表示用复数不要用单数
   7. 不要使用文件扩展名

5. 请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填

   1. 字段是类的属性；

   2. 说明是中文释义；

   3. 类型是属性类型，只有String、Number、Object、Array四种类型；

   4. 备注是一些解释，或者可以写一下例子，比如负责json结构的情况，最好写上例子，好让前端能更好理解；

   5. 是否必填是字段的是否必填。

   6. 另外在使用postman进行发送请求的时候，有三种常用的文件类型传递到后端
      

      form-data： 就是form表单中的multipart/form-data，会将表单数据处理为一条信息，用特定标签符将一条条信息分割开，而这个文件类型通常用来上传二进制文件。

      x-www-form-urlencoded：就是application/x-www-form-urlencoded，是form表单默认的encType，form表单会将表单内的数据转换为键值对，这种格式不能上传文件。

      raw：可以上传任意格式的文本，可以上传Text，JSON，XML等，但目前大部分还是上传JSON格式数据。当后端需要接收JSON格式数据处理的时候，可以采用这种格式来测试。

      因为GET请求查询参数在URL上，其他类型请求使用x-www-form-urlencoded方式向后端传值。

6. 返回参数结构有几种情况：

   1. 如果只返回接口调用成功还是失败（如新增、删除、修改等），结构体是code和message两个参数；
   2. 如果要返回某些参数，结构是code/mesage/data，是data里写返回的参数,data是object类型；
   3. 如果要返回列表，结构体是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

注意：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开

四、总结

RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。