什么是好的API与设计流程和设计原则_百度知道
什么是好的API与设计流程和设计原则
我有更好的答案
安全是恒久的话题，对于基于WSDL和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。那么，RESTful API有无成熟可用规范或实现框架呢？如何保证RESTful API的安全性呢？如何对RESTful API进行版本控制，请分享您认为实用的做法？HTTP1.1规范中给出的动词对于设计RESTful API够用吗？您在实际项目中会扩展自己的动词吗？在什么情况下需要扩展？今年5月份发布的JAX-RS 2.0规范对于RSTfulAPI的设计最有价值的特性是哪个（些）? 它（们）用于解决什么问题？能否为InfoQ的读者们推荐一款实用的RESTful API开发框架，并说明您的推介理由。HTTP2.0规范正在制定当中，您对它的期待是什么？InfoQ：什么是好的RESTful API？相信每个人都有自己的评判标准。那么，您认为一个好的RESTful API应该具有哪些特征呢？ 李锟：一个好的RESTful API，应该具备以下特征：这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。这个API应该是松耦合的。RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。这个API中所使用的表述格式应该是常见的通用格式在RESTful API中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。使用HTTP响应状态代码来表达各种出错情况HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：status code和reason phase。两部分都是可定制的，也可以使用标准的status code，只定制reason phase。如果一个所谓的“RESTful API”对于任何请求都返回200 OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。这个API应该对于HTTP缓存是友好的充分利用好HTTP缓存是RESTful API可伸缩性的根本。HTTP协议是一个分层的架构，从两端的user agent到origin server之间，可以插入很多中间组件。而在整个HTTP通信链条的很多位置，都可以设置缓存。HTTP协议内建有很好的缓存机制，可以分成过期模型和验证模型两套缓存机制。如果API设计者完全没有考虑过如何利用HTTP缓存，那么这个API的可伸缩性会有很多问题。李建业：首先说明一下，对REST这个概念，我一般把它理解为REST风格的架构，但是现在实践中最为广泛认知的是HTTP，而它是REST的一个实现，所以RESTful API也可以不太严格的指基于HTTP的API——当然，即使是不严格的时候，API本身也应该力求遵循REST架构风格。我认为，一个RESTful API最重要的一点应该是——“尽可能少的先验信息”，这一条也同时是我判断一个好的RESTful API的标准。比如HTTP动词，在实践中，大家可能会常常纠结于有效利用 HTTP 动词，但这却并不是特别重要的事情——除非你理解这么做的价值。HTTP 动词最重要的地方在于它是标准阐明了的行为，也就是说，如果我们的“客户端”遵循约定，那么就不必要发明新的动词，也就不必增加“先验信息”；但是，所谓“先验信息”，针对的是客户端——对API来说就是调用者，对于一些企业内部系统，或者一些传统系统，由于“资源”很稳定，对资源的操作也很稳定，这些系统的“调用客户端”不是浏览器而是另一个系统，此时如果强制对应到HTTP动词，反而会变成额外的“先验信息”，这时我就不会太拘泥HTTP动词，自己制定一套动词放在参数中也可以接受——只要动词不变化，这个系统依然是REST风格的。再比如Response里面的Content-Type，这个有时会被新手忽略，但这其实很重要，因为一般涉及到系统间协同的API，往往不会使用普通的文本，比较常见的是使用json表达复杂结构，而这与通常的缺省理解不同（缺省一般会认为是text/plain和text/html），所以如果在API中忘记用Content-Type进行区分的话，后续对多种类型的客户端接入的支持就会变成陷阱（我们多次遇到过这个问题）。而如果一开始就检查是否增加先验知识（缺省Content-Type为plain或者允许指定Content-Type），那这一困难就可以避免了。丁雪丰：首先，应该正确地使用HTTP的统一接口，比如HTTP的动词，如果不分青红皂白清一色POST那显然还有改进的余地；其次，资源有合适的粒度，可以从三个方面来评判资源的粒度是否合理——网络的效率、表述的大小以及客户端使用时的易用程度；最后，是表述的设计，除了表述的正文内容，还有其中的URI和链接，这些都是评判一个RESTful API好坏的标准。马钧：在我看来，一个好的API标准，就是能尽量利用到HTTP协议的特性，将HTTP当成一种转移协议，而不是传输协议。包括但不限于：利用HTTP的各种动词来明确操作；包含有内容协商，可以根据请求头提供的参数选择一个资源最合适的媒体类型、语言、字符集和编码的表现；使用不同的返回代码来描述各种状态。但实际上见到过的很多声称RESTful API，包括国内的和国外的，能符合这些条件的并不多。parse.com提供的API是我见到过的较为不错的RESTful API，可以作为范例参考。InfoQ：安全是恒久的话题，对于基于WSDL和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。那么，RESTful API有无成熟可用规范或实现框架呢？如何保证RESTful API的安全性呢？李锟：保证RESTful API的安全性，主要包括三大方面：a) 对客户端做身份认证b) 对敏感的数据做加密，并且防止篡改c) 身份认证之后的授权对客户端做身份认证，有几种常见的做法：在请求中加签名参数为每个接入方分配一个密钥，并且规定一种签名的计算方法。要求接入方的请求中必须加上签名参数。这个做法是最简单的，但是需要确保接入方密钥的安全保存，另外还要注意防范replay攻击。其优点是容易理解与实现，缺点是需要承担安全保存密钥和定期更新密钥的负担，而且不够灵活，更新密钥和升级签名算法很困难。使用标准的HTTP身份认证机制HTTP Basic身份认证安全性较低，必须与HTTPS配合使用。HTTP Digest身份认证可以单独使用，具备中等程度的安全性。HTTP Digest身份认证机制还支持插入用户自定义的加密算法，这样可以进一步提高API的安全性。不过插入自定义加密算法在面向互联网的API中用的不是很多。这个做法需要确保接入方“安全域-用户名-密码”三元组信息的安全保存，另外还要注意防范replay攻击。优点：基于标准，得到了广泛的支持（大量HTTP服务器端、客户端库）。在服务器端做HTTP身份认证的职责可以由Web Server（例如Nginx）、App Server（例如Tomcat）、安全框架（例如Spring Security）来承担，对应用开发者来说是透明的。HTTP身份认证机制（RFC 2617）非常好地体现了“分离关注点”的设计原则，而且保持了操作语义的可见性。缺点：这类基于简单用户名+密码机制的安全性不可能高于基于非对称密钥的机制（例如数字证书）。使用OAuth协议做身份认证OAuth协议适用于为外部应用授权访问本站资源的情况。其中的加密机制与HTTP Digest身份认证相比，安全性更高。需要注意，OAuth身份认证与HTTP Digest身份认证之间并不是相互取代的关系，它们的适用场景是不同的。OAuth协议更适合于为面向最终用户维度的API提供授权，例如获取隶属于用户的微博信息等等。如果API并不是面向最终用户维度的，例如像七牛云存储这样的存储服务，这并非是OAuth协议的典型适用场景。对敏感的数据做加密，并且防止篡改，常见的做法有：部署SSL基础设施（即HTTPS），敏感数据的传输全部基于SSL。仅对部分敏感数据做加密（例如预付费卡的卡号+密码），并加入某种随机数作为加密盐，以防范数据被篡改。身份认证之后的授权，主要是由应用来控制。通常应该实现某种基于角色+用户组的授权机制，这方面的框架有不少（例如Spring Security），不过大多数开发团队还是喜欢自己来实现相关功能。李建业：我不认为安全是RESTful API需要考虑的问题，事实上我觉得这是两个正交的问题。当然，如果使用RESTful API来提供认证、授权和身份管理，那也算是双方有关系，但是这和其它风格的API设计所要考虑的问题似乎没什么区别，不值得特别注意。但是在具体设计层面，这两者的“正交点”上似乎确实有些问题，因为REST是一个推崇状态无关原则的架构风格，而认证和授权通常基于第三方解决方案，所以往往会出现违背有状态约束的问题，这个地方我也没有特别的想法，当然这个困难和原问题关系不大。至于WS-族的协议，我不太了解，不太能参与讨论。丁雪丰：对于RESTful API，常见的安全措施都是可以继续使用的。例如，为了防篡改，可以对全部参数进行签名；为了防范重放攻击可以在请求中增加一次性的Token，或者短时间内有效的Token；对内容加密可以实现数据防泄露……；对于DDoS攻击，各种HTTP流量清洗策略，都可以继续发挥作用，因为这就是基本的HTTP请求。在授权和认证方面，OAuth 2.0已经基本成熟了，并且得到了广泛地应用。如果可以，接入第三方账户体系是个不错的选择，比如Google和Facebook的，国内的当然也有几个候选。马钧：个人认为RESTful的安全性分为几个层次，在安全要求较高的场合，可以通过HTTPs这样的加密协议来保证网络层的安全，应用层的安全可以通过OAuth实现认证，而对于资源的访问授权，则只能依靠应用程序来实现了。InfoQ：如何对RESTful API进行版本控制，请分享您认为实用的做法？李锟：一个比较简单实用的做法是直接在URI中插入版本号，这样做允许多个版本的API并行运行。另一个做法是在HTTP请求中加入自定义头信息，标明使用的版本号。不过这个做法其实对浏览器不够友好，简单地使用浏览器+HTML无法测试。李建业：目前比较好的方式还是在uri设计中添加版本信息，其它方法都不如这个实用。丁雪丰：个人认为最好的版本化，就是没有明显的版本。在对已发布的服务进行变更时，要尽量做到兼容，其中包括URI、链接和各种不同的表述的兼容，最关键的就是在扩展时不能破坏现有的客户端。例如，要变更一个参数，可以选择同时兼容新旧两种输入，或者保持老参数不动，提供一个新的参数，在文档中必须做出说明，不推荐新用户再继续使用之前的参数。如果必须要进行不兼容的变更，那么可以选择标记不同的版本号，这时可以选择在路径或参数中增加版本信息。也有做法是增加HTTP标头，只是在调用时会稍有不便，推荐前两种方法。马钧：RESTfulAPI的版本升级，尽量兼容之前的版本，保证原有的API都能正常工作，可以通过HTTP 301转跳到新的资源。另外一种实用的做法就是在url中保留版本号，同时提供多个版本供客户端使用，如 v1.rest.com 或者 rest.com/v1/ 这样。InfoQ：HTTP1.1规范中给出的动词对于设计RESTful API够用吗？您在实际项目中会扩展自己的动词吗？在什么情况下需要扩展？李锟：这个问题取决于设计者如何看待和设计资源。如果资源抽象做的很好，对于某个资源的任何操作，通常都能够映射到CRUD四个类别中。CRUD四个类别对于操作资源来说，绝大多数情况下是完备的。HTTP的GET/POST/PUT/DELETE四个方法，对于CRUD四个类别的操作来说是足够的，映射关系是Create-POST/Retrieve-GET/Update-PUT/Delete-DELETE。我们通常不会选择创建自己的动词，这样做对于客户端开发者来说，需要更多的学习成本。如果在资源上定义的操作过多，我们会选择拆分出更多的资源。李建业：一般是够用的，有时一些“不够用”的场景是由于我们没有设计出合理的资源，比如批量操作。但是，正如之前所说的那样，对于某些内部的、传统的（因此模型稳定且已知）系统，API提供者和调用者会有自已的固定动词表，此时没必要拘泥。另外，我不建议扩展动词，一旦扩展了动词，其实已经破坏了我之前说的*“尽可能少的先验信息”*，那么，扩展动词和重新设计动词的成本差别不大。基于这个考虑，我建议尽可能保持动词不变，除非你想重新设计动词表。丁雪丰：一般情况下，常用的HTTP动词是够用的，并没有出现一定要自己扩展动词的情况。其实，最常用的也就是GET、POST、DELETE和PUT，而HEAD、OPTIONS、TRACE则基本用不太到。如果出现一时找不到合适的动词，安全幂等的操作用GET，其他都可以用POST，在设计资源时稍加考虑即可。马钧：在我的实际项目中，只用到了POST，PUT，DELETE，GET这四个动词。InfoQ：今年5月份发布的JAX-RS 2.0规范对于RSTfulAPI的设计最有价值的特性是哪个（些）? 它（们）用于解决什么问题？李锟：REST开发框架RESTEasy项目负责人Bill Burke，去年写了一篇文章介绍JAX-RS 2.0。我同意Bill在文章中的观点，在JAX-RS 2.0增加的内容中，最重要的三部分为：a) Client API——用来规范化JAX-RS客户端的开发方式。b) Server-side Asynchronous HTTP——用来实现服务器端推送功能，而不需要依靠低效的轮询方式。c) Filters and Interceptors——用来分离关注点，将鉴权、日志等逻辑与业务逻辑分离开，更好地实现代码重用。这三部分的内容对于开发者来说都很有用。遵循JAX-RS规范做开发，可以确保服务器端以及客户端代码的可移植性。李建业：我个人关注异步API这部分，主要是因为流式服务将会越来越多，那将大量需要这类支持。InfoQ：能否为InfoQ的读者推荐一款实用的RESTful API开发框架，并说明您的推介理由。李锟：这个问题我就不详细回答了。不同的编程语言有不同的REST开发框架，对于REST的支持程度也不同。开发RESTful API的需求范围很广，可选择的开发框架的范围也很广。保持多样性是繁荣生态环境的基础。像Java就有支持JAX-RS规范的Jersey、RESTEasy、Restlet、Apache CXF，和不支持JAX-RS规范的Spring MVC等等很多框架。这些框架目前都做的不错。我对框架的选择没有倾向性。RESTful API设计的最佳实践应该是通用的，而不是必须依赖某种特定的开发框架。李建业：不好意思，这个我不太重视，没法推荐，不过我可以解释一下为什么对RESTful API框架不感冒的原因。REST作为一个架构风格，对我们的系统开发有很大影响，但是这些影响一般是针对架构（例如状态无关）或者设计（例如资源识别）上的，所以一旦涉及到具体实现，主要工作就基本结束了，此时开发框架能做的事也就只有简化编程了（相较而言，有的框架还能起到引导设计的作用），而由于RESTful会抽象动词，所以实现层面中和API规范相关的工作本来就不多，那么框架的价值就更小了。当然，我们也不可能直接基于servlet/rakc/wsgi来开发，不过一般的编程语言都会提供一些简单的url route/match策略，我们使用这些就足够了。另外，有些框架能帮我们生成全部的动词支持，但这也未必是好事，我一般倾向于按需实现——用到了再支持，这就更不需要太关注开发框架对RESTful的支持了。丁雪丰：由于本人是Spring的拥护者，工作中也一直在使用Spring，所以在选择框架时会更多地倾向Spring MVC（并不是说别的框架不好，这里有些个人主观的成份）。如果一定要选择其他框架，也要选择能够方便与Spring集成的框架。如果在项目中已经使用了Spring，那么没有什么理由不选择Spring MVC，鉴于目前Spring在各种项目中的高出镜率，相信一般情况下都会选择Spring MVC。REST的成熟度模型中，第三层就是HATEOAS，Spring目前还提供了Spring Hateoas子项目，对链接、资源等方面的支持都做了一定的增强。马钧：我目前在实际项目中使用的是Spray，这是一个开源的 REST/HTTP 工具包和底层网络 IO 包，基于 Scala 和 Akka 构建。轻量级、异步、非堵塞、基于 actor 模式、模块化和可测试是Spray的特点。InfoQ：HTTP2.0规范正在制定当中，您对它的期待是什么？李锟：我的期待包括两个方面：应该做的和不应该做的。HTTP/2.0规范应该做的：与HTTP/1.1协议保持兼容。兼容的含义是说两者可以并存，客户端应用可以根据服务器端的能力，自由地选择使用HTTP/2.0还是HTTP/1.1，而且选择过程对应用来说是透明的。改进HTTP协议（作为资源的统一接口）之中操作语义表达方式的语法，提高网络传输效率。更好地模块化，这样HTTP/2.0协议的实现能够更好地模块化。应用程序可根据需要选择适当的模块，而不是要么全有、要么全无。废弃掉HTTP/1.1协议中一些很少有人用到的部分，例如采用管道（pipelining）方式发送请求。增加更多的动词，以适应除CRUD之外的其他场景。HTTP/2.0规范不应该做的：HTTP/2.0协议不应该把底层的数据加密机制（即SSL）作为必选项。HTTP/2.0协议不应该背离REST架构风格的约束，尤其是要确保操作语义对于中间组件的可见性。在上面这两个方面，Roy Fileidng曾经与SPDY协议设计者Mike Belshe发生过激烈争论，详情请看：Roy Fielding谈Google SPDY协议李建业：对此规范关注不多，不知道会不会有对于流的支持，目前我所知道的只有chunk方式进行简单的支持，但是真正的流需要区分数据通道和控制通道——哪怕是逻辑上的区分，这样就直接对REST风格产生了很大冲击，考虑到流式服务在未来的发展潜力，我特别期待业界在这方面有所进展。丁雪丰：HTTP 2.0很大程度上是借鉴了Google的SPDY，就我而言，首先，希望这个规范能做到与HTTP 1.1的兼容，使用者如果只认识1.1，那么2.0能优雅“降级”；其次，希望2.0能带来更好的性能，SPDY在这方面还是有所改进的，希望HTTP 2.0能再接再厉；最后，希望这个规范能在最终定稿时附带一个最佳实践，正确引导人们合理地使用HTTP 2.0。马钧：没研究过，估计即使出来，1.1还有很长的生命周期，不会很快被取代。
为您推荐：
其他类似问题
换一换
回答问题，赢新手礼包
个人、企业类
违法有害信息,请在下方选择后提交
色情、暴力
我们会通过消息、邮箱等方式尽快将举报结果通知您。如何设计一个优秀的API - 文章 - 伯乐在线
& 如何设计一个优秀的API
到目前为止，已经负责API接近两年了，这两年中发现现有的API存在的问题越来越多，但很多API一旦发布后就不再能修改了，即时升级和维护是必须的。一旦API发生变化，就可能对相关的调用者带来巨大的代价，用户需要排查所有调用的代码，需要调整所有与之相关的部分，这些工作对他们来说都是额外的。如果辛辛苦苦完成这些以后，还发现了相关的bug，那对用户的打击就更大。如果API经常发生变化，用户就会失去对提供方失去信心，从而也会影响目前的业务。
但是我们为什么还要修改API呢？为了API看起来更加漂亮？为了提供更多功能？为了提供更好的性能？还是仅仅觉得到了改变了时候了？对于用户来说，他们更愿意使用一个稳定但是看起来不那么时髦的API，这并不意味着我们不再改进API了。当糟糕的API带来的维护成本越来越大时，我想就是我们去重构它的时候。
如果可以回头重新再做一遍，那么我心目中的优秀的API应该是怎么样的？
判断一个API是否优秀，并不是简单地根据第一个版本给出判断的，而是要看随着时间的推移，该API是否还能存在，是否仍旧保持得不错。槽糕的API接口各种各样，但是好的API接口对于用户来说必须满足以下几个点：
易学习：有完善的文档及提供尽可能多的示例和可copy－paste的代码，像其他设计工作一样，你应该应用。
易使用：没有复杂的程序、复杂的细节，易于学习；灵活的API允许按字段排序、可自定义分页、 排序和筛选等。一个完整的API意味着被期望的功能都包含在内。
难误用：对详细的错误提示，有些经验的用户可以直接使用API而不需要阅读文档。
而对于开发人员来说，要求又是不一样的：
易阅读：代码的编写只需要一次一次，但是当调试或者修改的时候都需要对代码进行阅读。
易开发：个最小化的接口是使用尽可能少的类以及尽可能少的类成员。这样使得理解、记忆、调试以及改变API更容易。
如何做到以上几点，以下是一些总结：
1、 面向用例设计
如果一个API被广泛使用了，那么就不可能了解所有使用该API的用户。如果设计者希望能够设计出被广泛使用的API，那么必须站在用户的角度来理解如何设计API库，以及如何才能设计出这样的API库。
2、 采用良好的设计思路
在设计过程中，如果能按照下面的方式来进行设计，会让这个API生命更长久
面向用例的设计，收集用户建议，把自己模拟成用户，保证API设计的易用和合理
保证后续的需求可以通过扩展的形式完成
第一版做尽量少的内容，由于新需求可以通过扩展的形式完成，因此尽量少做事情是抑制API设计错误的一个有效方案
对外提供清晰的API和文档规范，避免用户错误的使用API，尤其是避免API（见第一节）靠后级别的API被用户知晓与误用
除此之外，下面还列出了一些具体的设计方法：
方法优于属性
工厂方法优于构造函数
避免过多继承
避免由于优化或者复用代码影响API
面向接口编程
扩展参数应当是便利的
对组件进行合理定位，确定暴露多少接口
提供扩展点
3、 避免极端的意见
在设计API的时候，一定要避免任何极端的意见，尤其是以下几点：
必须漂亮（API不一定需要漂亮）
API必须被正确地使用（用户很难理解如何正确的使用API，API的设计者要充分考虑API被误用的情况：如果一个API可能会被误用，那么它一定会被误用）
必须简单（我们总会面临复杂的需求，能两者兼顾的API是更好的API）
必须高性能（性能可以通过其他手段优化，不应该影响API的设计）
必须绝对兼容（尽管本文一直提到如何保证兼容，但是我们仍然要意识到，一些极少情况下会遇到的不兼容是可以容忍的）
4、 有效的API评审
API设计完成以后，需要经过周密的设计评审，评审的重点如下：
用例驱动，评审前必须提供完善的使用用例，确保用例的合理性和完备性。
一致性，是否与系统中其他模块的接口风格一致，是否与对称接口的设计一致。
简单明了，API应该简单好理解，容易学习和使用的API才不容易被误用，给我们带来更多的麻烦。
API尽可能少，如果一个API可以暴露也可以不暴露，那么就不要暴露他，等到用户真正有需求的时候再将它成为一个公开接口也不迟。
支持持续改进，API是否能够方便地通过扩展的方式增加功能和优化。
5、 提高API的可测试性
API需要是可测试的，测试不应依赖实现，测试充分的API，尤其是经过了严格的“兼容性整合测试”的API，更能保证在升级的过程中不出现兼容性问题。兼容性整合测试，是指一组测试用例集合，这组测试用例会站在使用者的立场上使用API。在API升级以后，再检测这组测试用例是否能完全符合预期的通过测试，尽可能的发现兼容性问题。
6、 保证API的向后兼容
对于每一个API的设计者来说，都渴望做到“向后兼容”，因为不管是现在的API用户，还是潜在的API用户，都只信任那些可兼容的API。但向后兼容有多个层次上的意义，而且不同层次的向后兼容，也意味着不同的重要性和复杂度。
7、 保持逐步改善
过去我们总希望能将现有的“不合理”的设计完全推翻，然后按照现在“美好”的思路，重新设计这个API，但是在一段时间以后，又会碰到一样的状况，需要再推翻一次。 如果我们没有有效的逐步改善的办法，依靠推翻现有设计，重新设计API只能让我们回到起点，然后重现之前的过程。 要有一套行之有效的持续改善的办法来在API兼容的同时，改善API使之更好。
8、 把握API的生命周期
每一个API都是有生命周期的，我们需要让API的生命周期更长，并且在API的生命周期结束时能让其平滑的消亡。
告诉用户我们是如何设计的，避免误用，提供指导，错误的使用往往是缩短API寿命的一大杀手
提供试用期，API不可能一开始就是稳定，经过试用的API才能有更强的生命力
为API分级：内部使用；二次开发使用；开发或试用中；稳定；弃用API。避免API被滥用的同时，我们可以通过调整API的级别，来扩大其影响力，也能更优雅的结束一个API的生命周期。
开发API的过程其实就是一个沟通交流的过程。沟通的双方就是API用户和API设计者。
9、 一些具体的实施方案
在一个API不可避免要消亡或者改变的时候，我们应该接受并且面对这个事实，下面列举了几种保证兼容性的前提下，对API进行调整的办法：
将API标记为弃用，重新建立一个新的API。如果一个API不可避免要被消亡，这是唯一的办法。
为其添加额外的参数或者参数选项来实现功能添加
将现有API拆成两部分，提供一个精简的核心API，过去的API通过封装核心API上实现。这通常用于解决用户需要一个代码精简的版本时。
在现有的API基础上进行封装，提供一个功能更丰富的包或者类
一些好的API示例：
，这里是文档的，同时提供了一个非常方便的。
，这里有一个非常详尽的文档。
可能感兴趣的话题
API必须被正确地使用（用户很难理解如何正确的使用API，API的设计者要充分考虑API被误用的情况：如果一个API可能会被误用，那么它一定会被误用）
很明显过度考虑API被误用情况，只会降低你的系统性能，再没有其他什么好处了。
关于伯乐在线博客
在这个信息爆炸的时代，人们已然被大量、快速并且简短的信息所包围。然而，我们相信：过多“快餐”式的阅读只会令人“虚胖”，缺乏实质的内涵。伯乐在线内容团队正试图以我们微薄的力量，把优秀的原创文章和译文分享给读者，为“快餐”添加一些“营养”元素。
新浪微博：
推荐微信号
（加好友请注明来意）
– 好的话题、有启发的回复、值得信赖的圈子
– 分享和发现有价值的内容与观点
– 为IT单身男女服务的征婚传播平台
– 优秀的工具资源导航
– 翻译传播优秀的外文文章
– 国内外的精选文章
– UI,网页，交互和用户体验
– 专注iOS技术分享
– 专注Android技术分享
– JavaScript, HTML5, CSS
– 专注Java技术分享
– 专注Python技术分享
& 2018 伯乐在线