简单的网络api接口设计

网络API接口设计

手机App以及使用了Ajax技术或作了先后端分离的页面都须要经过网络API（Application Programming Interface）和后台进行交互，所谓API，指的应用程序的编程接口；而网络API通畅指的是基于HTTP或HTTPS协议的一个URL（统一资源定位符），经过这个URL咱们可让服务器对某个资源进行操做并返回操做的结果。基于HTTP(S)协议最大的好处就在于访问起来很是的简单方便，并且没有编程语言和应用环境上的差异。

设计原则

关键问题

为移动端或者PC端设计网络API接口一个很是重要的原则是：根据业务实体而不是用户界面或操做来设计。若是API接口的设计是根据用户的操做或者界面上的功能设置来设计，随着需求的变动，用户界面也会进行调整，须要的数据也在发生变化，那么后端开发者就要不停的调整API，或者给一个API设计出多个版本，这些都会使项目的开发和维护成本增长。

下面是某个网站开放API的接口，能够看出API的设计是围绕业务实体来进行的，并且都作到了“见名知意”。

评论
comments/show	获取某条微博的评论列表
comments/by_me	本身的评论列表
comments/to_me	收到的评论列表
comments/mentions	@了本身的评论列表
comments/create	建立一条评论
comments/delete	删除一条评论
comments/reply	回复一条评论

注意：上面的API接口并非REST风格的，关于REST的知识，能够阅读阮一峰老师的《理解RESTful架构》以及《RESTful API设计指南》。

API接口返回的数据一般都是JSON或XML格式，咱们这里不讨论后者。对于JSON格式的数据，咱们须要作到不要返回null这的值，由于这样的值一旦处置失当，会给移动端的开发带来麻烦（移动端可能使用强类型语言）。要解决这个问题能够从源头入手，在设计数据库的时候，尽可能给每一个字段都加上“not null”约束或者设置合理的默认值约束。

其余问题

1. 更新提示问题：设计一个每次使用系统首先要访问的API，该API会向移动端返回系统更新的相关信息，这样就能够提高用户更新App了。
2. 版本升级问题：API版本升级时应该考虑对低版本的兼容，同时要让新版本和旧版本都可以被访问，能够在URL中包含版本信息或者在将版本号放在HTTP(S)协议头部，关于这个问题有不少的争论，有兴趣的能够看看stack overflow上面对这个问题的讨论。
3. 图片尺寸问题：移动端对于一张图片可能须要不一样的尺寸，能够在获取图片时传入尺寸参数并获取对应的资源；更好的作法是直接使用云存储或CDN（直接提供了图片缩放的功能），这样能够加速对资源的访问。

文档撰写

下面以设计评论接口为例，简单说明接口文档应该如何撰写。

评论接口

全局返回状态码

返回码	返回信息	说明
10000	获取评论成功
10001	建立评论成功
10002	没法建立评论	建立评论时因违反审核机制而没法建立
10003	评论已被删除	查看评论时评论因不和谐因素已被删除
10004	……	……

1. GET /comments/{article-id}

   开发者：王大锤

   最后更新时间：2018年8月10日

   标签：v 1.0

   接口说明：获取指定文章的全部评论

   使用帮助：默认返回20条数据，须要在请求头中设置身份标识（key）

   请求参数：

   参数名	类型	是否必填	参数位置	说明
   page	整数	否	查询参数	页码，默认值1
   size	整数	否	查询参数	每次获取评论数量（10~100），默认值20
   key	字符串	是	请求头	用户的身份标识

   响应信息：

   {
       "code": 10000,
       "message": "获取评论成功",
       "page": 1,
       "size": 10,
       "totalPage": 35,
       "contents": [
           {
               "userId": 1700095,
               "nickname": "王大锤",
               "pubDate": "2018年7月31日",
               "content": "小编是否是有病呀"
               /* ... */
           },
           {
               "userId", 1995322,
               "nickname": "白元芳",
               "pubDate": "2018年8月2日",
               "content": "楼上说得好"
               /* ... */
           }
       ]
       /* ... */
   }

2. POST /comments/{article-id}

   开发者：王大锤

   最后更新时间：2018年8月10日

   标签：v 1.0

   接口说明：为指定的文章建立评论

   使用帮助：暂无

   请求参数：

   参数名	类型	是否必填	参数位置	说明
   userId	字符串	是	消息体	用户ID
   key	字符串	是	请求头	用户的令牌
   content	字符串	是	消息体	评论的内容

   响应信息：

   {
       "code": 10001,
       "message": "建立评论成功",
       "comment": {
           "pubDate": "2018年7月31日",
           "content": "小编是否是有病呀"
           /* ... */
       }
       /* ... */
   }