Web API设计经验与总结

  在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建。 通过Http协议的形式来. 以Get/Post方式发送请求, 返回json格式(数据更小巧且自描述能力强)的数据。这里就不在介绍REST API 的好处和不足。这些网上一大堆资料。今天就说说,如何构建优秀的REST API ?

  目前,各大互联网公司, 对自身的REST Api设计有各自的标准,他们的Api 的设计也非常成熟。 那么,我们应该如何更好的设计我们的接口, 来提高我们 API 的可用性,易用性,可维护性与可扩展性呢?

  一. API 设计方案
  1. Http的请求分为URL约定规则、请求参数规则
    URL规则: http://{server}/{product}/{version}/{logic}/{method}?{query_string}

    server: 为具体的服务域名
    product: 为应用工程名
    version: 为具体版本号, 便于将来的功能扩展, 可以暂定为 v1, v2
    logic: 为具体业务逻辑的初步划分, 比如后端管理方法, app端的请求方法
    method: 具体业务的方法

    具体的请求参数, 由指定的method方法决定, 全都作为HTTP GET/POST的参数列表。

    这里很多人会问为什么把 method 和 version 放到在URI中?

    因为这样可以使API 版本化,方便版本控制,同时也便于日后API的分流。当然关于是否将版本信息放入url还是放入请求头里面,曾经有过很激烈的争论,各有各的道理。我个人认为放到 URL 中会好一些。具体的大家还是根据自己的业务场景,综合考量吧。

  2. Http的响应规则
    HTTP响应码为200, 返回结果为JSON字符串的形式:
    如果响应结果正确,则返回结果如下所示:
    {  
      data : { // 请求数据,对象或数组均可
        user_id: 123,
        user_name: "zwz",
        user_avatar_url: "http://www.abc.com/1.jpg"
        ...
      },
      msg : "done", // 请求状态描述,调试用
      success : 1,
      code" : 1001, // 业务自定义状态码
      extra : { // 其他扩展的数据,字段、内容不定
        type: 1,
        desc: "签到成功!"
      }
    }

    如果响应结果失败,则返回如下结果:
    {
      data : { // 请求数据,对象或数组均可
      },
      msg : "Internal Server Error", // 请求状态描述,调试用
      success : 0,
      code : 5001, // 业务自定义状态码
      extra : {
      }
    }

  3. Auth 权限验证

    API 的权限验证,有很多方案,目前成熟的OAuth 2.0框架等,不过 ,最简单的还是利用 Http Header 来完成这一目标。 将token 通过 Header 传递。来实现权限验证。

  4. API 在设计的时候,最好不要将业务错误码与HTTP状态码的绑定,重新定义一套业务错误码,来区分HTTP 的状态码。
    状态码的定义也最好有一套规范,类似于HTTP 的状态码,可以按照用户相关、授权相关、各种业务,做简单的分类。
    // Code 业务自定义状态码定义示例
    // 授权相关
    1001: 无权限访问
    1002: access_token过期
    1003: unique_token无效
    ...

    // 用户相关
    2001: 未登录
    2002: 用户信息错误
    2003: 用户不存在

    // 业务相关
    3001: 业务XXX
    3002: 业务XXX

    // 系统异常
    5001:Internal Server Error

   二. 其他一些建议:

    1. 规范统一的命名
      使用驼峰式或者下划线格式都可以,统一规范就行。不过,目前基本都是统一小写加下划线比较好。如:user_id,user_name,user_age等。

    2. 语义清晰,遵守常用缩写
      字段的名字最好能体现字段的类型,遵守一些常用的缩写,如:user_name, task_desc, date_str 等

    3. 空值、空字段的处理
      空值、空字段的处理也是比较容易出问题。统一空值用null 。除了布尔类型的,其余的空值统一用null表示,客户端保证每种字段的null可以被正常处理。 

    4. 各个Action 尽量符合CRUD操作的原则。   

    5. 给不同类型设置默认空值
      除了null,尽量对字段设置“默认值”,如数字就是0,字符串就是空字符串"",数组就是空数组[],对象就是空对象{},这样可以避免客户端处理空值产生的异常。
      具体的要根据业务、前后端约定而定。
      比如,bool 类型的值,统一成数字0和1 。时间日期类型强制只能传标准GMT/UTC时间戳,然后由各自的客户端根据自己的时区、显示要求做处理后显示。

    6. 完整的URL
      API里面的数据也会有URL类型的,一般来说如用户的头像、各种图片、音频等资源,都是以URL链接的形式返回的。
      返回的URL一定要“完整”,主要指的是不要忘记URL里面的协议部分。应该是http://www.abc.com/1.jpg。

    7. REST 安全
      可以使用固有的 HTTP 基本验证,你还可以考虑通过支持表单验证,LTPA 验证,Open ID 验证等方式,来满足更多的企业安全要求。

    8. 尽量将API部署在专用域名之下。例如:https://api.example.com。

    9. API返回的数据格式,应该尽量使用JSON,避免使用XML。

    10. 返回正确 HTTP 响应代码,同时重新定义一套业务错误码,来区分HTTP 的状态码。

    11. 完善的文档,最好能自动生成在线API文档,这样文档能随时保持最新。
      目前有很多自动生成API 文档的攻击,例如:SwaggerUI。

时间: 2024-11-05 04:49:46

Web API设计经验与总结的相关文章

Web API 设计摘要

近期读了一本微电子书 Brian Mulloy 所著<Web API Design>感觉颇多收获,特对其内容做了个整理摘要以便回想其观点精华以指导日常工作中的设计思路. 本文主要讲述 Web API 设计,追求一种更务实的 REST 风格. 正如作者所说 REST 是一种架构风格,而非严格的标准,不是必需在形式定义上去做过多真论,究竟什么才是真正的 REST? 设计的目的是为了表达某样东西是怎样使用的,那么 API 设计的成功与否是由开发者是否可以高速上手并用的愉快. 以下讲述了 Web AP

Web API设计方法论--比较完整的web api 开发过程

为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护公共API.沿途将会有对有影响力的人物的访谈,甚至还有API及相关主题的推荐阅读清单. 这篇 InfoQ文章是 Web API从开始到结束系列文章中的一篇.你可以在这里进行订阅,以便能在有新文章发布时收到通知. 设计Web API不止是URL.HTTP状态码.头信息和有效负载.设计的过程--基本上是

Asp.net Web Api 设计

目录 Asp.net Web Api 设计[持续更新] 第一部分 基础知识 第一章 因特网.万维网和HTTP协议 1.1 Web体系结构 第二章 Web Api 2.1 什么是Web Api 2.6 Web Api 指南 第三章 Asp.Net Web Api Asp.net Web Api 设计[持续更新] 第一部分 基础知识 第一章 因特网.万维网和HTTP协议 1.1 Web体系结构 Web体系有三个核心概念:资源 .URL和表示.一个资源由一个URI进行标识,而HTTP客户端使用URI就

RESTFUL如何指导WEB API设计?

博主刚刚接触web开发的时候,写了一个接口 /get_article_info/1 获取id为1的这篇文章的内容,被前辈们看见了,前辈给我说我这个接口设计的不太好啊,不符合RESTFUL规范,当前辈们说出这些话的时候,我很迷惑,我写的接口不能够好好工作吗?能够正常返回内容啊,对于不存在的文章也能够在返回的内容体中提示不存在,而且接口的意思很明确,一看就能明白,这还有什么不好的地方吗? 一.RESTFUL是什么? RESTFUL是英文单词Representational State Transfe

web架构设计经验分享(转)

本人作为一位web工程师,着眼最多之处莫过于 性能与架构,本次幸得参与sd2.0大会,得以与同行广泛交流,于此二方面,有些心得,不敢独享,与众博友分享,本文是这次参会与众同撩交流的心得,有兴趣者可以查看视频 架构设计的几个心得: 一,不要过设计:never over design 这是一个常常被提及的话题,但是只要想想你的架构里有多少功能是根本没有用到,或者最后废弃的,就能明白其重要性了,初涉架构设计,往往倾向于设计大而化一的架构,希望设计出具有无比扩展性,能适应一切需求的增加架构,web开发领

如何设计出优美的Web API?

1. 概述 WEB API的应用场景非常丰富,例如:将已有系统的功能或数据开放给合作伙伴或生态圈:对外发布可嵌入到其他网页的微件:构建前后端分离的WEB应用:开发跨不同终端的移动应用:集成公司内部不同系统等等.在上述场景里,你可能是WEB API的使用者,也可能是设计者,但你知道如何评判WEB API的优劣吗? 2. 评判标准 我们可以从三个维度来评判一个WEB API的优劣: 易于使用:WEB API的用户是程序还是人?我觉得首先是人,然后是程序.为什么这么说呢?是否采用某个WEB API的决

How ASP.NET Web API 2.0 Works?[持续更新中…]

一.概述 RESTful Web API [Web标准篇]RESTful Web API [设计篇] 在一个空ASP.NET Web项目上创建一个ASP.NET Web API 2.0应用 二.路由 ASP.NET的路由系统:URL与物理文件的分离 ASP.NET的路由系统:路由映射 ASP.NET的路由系统:根据路由规则生成URL ASP.NET Web API路由系统的几个核心类型 Web Host下的URL路由 三.消息处理管道 ASP.NET Web API标准的"管道式"设计

难道没有人吐槽 Asp.net Web Api 的吗

一个APP新项目为了赶时髦,用上了Asp.net Web API,可能我不是太熟悉,经过我几天潜心研究,web api 确实没啥用,简直属于狗尾续貂之作. 新创建一个api controller,大概方法如下 public IEnumerable<string> Get(); public string Get(int id); public void Post([FromBody]string value); public void Put(int id, [FromBody]string

Web API接口设计经验总结

在Web API接口的开发过程中,我们可能会碰到各种各样的问题,我在前面两篇随笔<Web API应用架构在Winform混合框架中的应用(1)>.<Web API应用架构在Winform混合框架中的应用(2)--自定义异常结果的处理>也进行了总的介绍,在经过我的大量模块实践并成功运行后,总结了这篇随笔,希望对大家有所帮助. 1.在接口定义中确定MVC的GET或者POST方式 由于我们整个Web API平台是基于MVC的基础上进行的API开发,因此整个Web API的接口,在定义的时