&&9494 阅读
API（Application Programming Interface）提供了对某个问题的抽象，以及客户与解决该问题的软件组件之间进行交互的方式。组件本身通常以软件类库形式分发，它们可以在多个应用程序中使用。概括地说，API定义了一些可复用的模块，使得各个模块化功能块可以嵌入到终端用户的应用程序中去。
你可以为自己、你所在机构中的其他工程师或大型开发社区编写API。它可以小到只包含一个单独的函数，也可以大到包含数以百计的类、方法、全局函数、数据类型、枚举类型和常量等。它的实现可以是私有的，也可以是开源的。有关API的一个重要的基本定义是：API是一个明确定义的接口，可以为其他软件提供特定服务。
现代应用程序通常都是基于很多API建立起来的，而这些API往往又依赖于其他API。如图1-1中示例应用程序所示，该应用程序用到了3个类库（1、2、3）的API，而这3个API中有2个又用到了另两个类库（4和5）。举例来说，浏览图片的应用程序可能会用到加载GIF图片的API，而该API本身则可能又依赖更底层的压缩或解压缩数据的API。
图字翻译：
Application Code：应用程序代码
Library：类库
图1-1 从层次化API中调用例程的应用程序。每个方框代表一个软件类库，灰色部分表示其公共接口，对于类库而言即是其API，白色部分表示隐藏在API后面的具体实现。
API开发在现代软件开发中随处可见，其目的是为某个组件的功能提供一个逻辑接口，同时隐藏该模块内部的实现细节。举例来说，我们用来读取GIF图片的API可能仅仅提供一个LoadImage()方法，后者接收一个文件名作为参数，并返回一个2维的像素数组。所有文件格式和数据压缩的细节全部隐藏在这个看似简单的接口之下。这个概念也在图1-1中进行了说明，即客户端代码只能够通过该API的公有接口访问。API公有接口如图1-1中每个方框顶部的灰色区域所示。
为什么选用C++来描述API设计
虽然有很多通用API设计方法学（可适用于任何编程语言或编程环境）可以讲，但最终都需要使用一门特定的编程语言来表述。因此了解特定语言的特征以促进规范的API设计是非常必要的。所以，本书专门使用一种语言（C++）描述API设计的问题，而非分散内容使其适用于所有语言。然而，想要使用其他语言（如Java或C#）开发API的读者仍然可以从本书中获得许多通用的深刻见解。本书的直接目标读者是编写并维护API的C++工程师，他们的API要供给其他工程师使用。
目前，C++仍是大型软件项目中使用最广泛的编程语言之一，并且日渐成为注重代码性能项目的首选语言，因此，你可以在自己应用中选用的C和C++的API种类非常多（前面我已经列出一些）。本书重点关注如何使用C++编写优秀API，并引入了丰富的源代码示例以更好地阐述这些概念。也就是说，本书会涉及一些C++特有的主题，例如模板、封装、继承、命名空间、操作符、const正确性、内存管理、STL的使用、Pimpl惯用法，等等。
另外，在本书出版期间，C++也正经历着巨大的变革。新版的C++规范处于ISO/IEC的标准化进程中。目前，多数C++编译器遵循1998年首次发布的标准，即C++98。随后的标准于2003年出版，修正了前版的几处缺陷。自那时以来，标准委员会一直致力于一个重大的新版本规范。在标准被正式批准生效并确定发布日期之前，该版本一直被非正式地称为C++0x。当你读到本书时，新的标准可能已经发布了。但是，在我编写本书的期间，它仍然被称为C++0x。
尽管如此，C++0x已经达到标准化进程的高级阶段，我们可以满怀信心地预言一些新的特性。事实上，一些主流的C++编译器已经开始实现许多建议的新特性。在API设计方面，某些新特性可以用来构建更加优雅和健壮的接口。因此，我一直努力在整本书中强调和解释C++0x中的API设计。所以，本书在未来几年中应该依然具有参考价值。
为什么使用API
在软件项目中为什么要关注API，这一问题可以从两个方面理解：(1)为什么要设计并编写API？(2)为什么要在应用中使用其他人提供的API？我将在接下来的小节中回答这两个方面的问题，并指出在项目中使用API的各种好处。
如果你正在编写供其他开发人员使用的模块，不管他们是公司里的其他工程师还是外部客户，比较明智的办法是构建API来让他们访问这些功能。这么做会带来以下好处。
更健壮的代码
隐藏实现。通过隐藏模块内部实现的细节，开发人员就可以在未来的某个时间自由修改模块的实现而不给用户造成重大影响。如若不然，会导致以下结果：（1）代码的更新将会受到限制；（2）用户只有重写代码才能使用新版本的程序库。如果总是让用户不停地更新软件版本，他们很可能不愿再做更新，或者干脆弃用，另外寻找不需要太多维护工作的API。因此，优秀的API设计对业务或项目成功至关重要。
延长寿命。随着使用时间增长，那些公开了实现细节的系统的内部代码会变得错综复杂，系统的各个部分要依赖其他部分的内部实现细节。因此，系统将会变得脆弱、死板、不可移植且粘滞性高（Martin，2000）。如此一来，公司为了改善这些代码，就不得不花费大量人力财力，甚至推倒重写。事先花工夫做好API设计，而后维护好该设计以保证一致性，软件寿命就能延长，从长远看也能节省花费。在第4章的前面部分，我们会深入讨论该问题。
促进模块化。API通常用来完成一项具体的任务或用例。因此，API定义了一组具有一致目的的模块化的功能集。在大量API基础之上开发的应用，其结构将降低耦合而更加模块化，每一个模块的行为都不依赖其他模块的内部细节。
减少代码重复。代码重复是软件工程中最恶劣的行为之一，任何时候都要避免犯此类错误。通过把所有的代码逻辑置于一个严格的接口之后，让所有客户使用这个接口，就能将程序的某种行为统一处理。这样做意味着只需更新一处代码就可以改变向所有客户提供的API的行为。这样有助于消除代码中所有重复的实现。事实上很多的API就是这样实现的，人们首先发现有重复的代码，然后制作统一的接口取代这些重复代码，于是就产生了API。这是一件好事。
消除硬编码负担。很多程序可能包含硬编码的值，并在整个代码中不断复制。例如，在需要写日志文件的地方就使用具体的文件名“myprogram.log”。我们可以使用API来提供这些信息，而不用在整个代码层面复制这些常量，例如，使用GetLogFilename() API调用代替硬编码的“myprogram.log”字符串。
易于改变实现。如果将所有的实现细节隐藏在公共接口背后，就可以在不影响任何依赖此API代码的情况下改变其内部的实现细节。例如，可以将原本使用std::string解析文件的方式变为分配、释放、再分配char*缓冲区的方式。
易于优化。成功隐藏了实现细节后，在优化API的性能时就不用操心更改客户端代码。例如，可以利用加设缓存的方案优化某个计算密集型的方法。之所以这样做是因为所有读写潜在数据的操作都是通过该API进行的，因此该API更确切地知道何时缓存中的结果无效并且需要重新计算结果。
代码重用就是使用已有的软件去构建新的软件。这是现代软件开发所追求的一个神圣的目标。API提供了一种代码复用的机制。
在早期的软件开发中，有种情况很常见，即公司不得不为其制作的任一应用编写所有代码。如果某个程序需要读取GIF图片或者解析文本文件，公司不得不自己编写全部代码。如今，随着优秀的商业库和开源库的增多，重用别人已经编写过的代码变得非常简单。举例来说，如今已经有各种开源的读取图像的API和解析XML的API供人们下载和使用。这些库被世界上许多程序开发人员不断地改进和调试，同时也已经在很多其他程序中被实践检验过。
通过使用不同的组件（它们用于构建应用程序各个模块）并借助组件已发布的API相互通信，软件开发从本质上已变得更加模块化。这种做法的好处是不需要了解每个软件组件的所有细节，如同前面提到的建造房屋的比喻，可以将很多细节问题委托给专业承包商。这样能够缩减开发周期，这一方面是因为可以重用已有的代码，另一方面则因为可以将各种组件的开发计划分离，还可以让开发者把重点放在核心业务逻辑上，而不必浪费时间重新发明轮子。
然而，实现代码重用的一个障碍是，常常需要比原本计划更加通用的接口，因为其他客户可能有额外的期望和需求。因此有效的代码重用来自对软件客户的深入了解以及结合了客户和自身利益的系统设计。
C++ API和WEB
依赖第三方API的应用程序在云计算领域里越来越普遍。该领域中，Web应用越来越依赖Web服务（API）为其提供核心功能。对于Web混搭应用程序（mashup），应用程序本身有时仅仅是对多种已有服务进行再次封装，从而提供新的服务。例如，将Google地图API和本地犯罪统计数据库相结合就可以为犯罪数据提供一个基于地图的界面。
实际上，花一些时间强调C++ API设计在Web开发中的重要性是值得的。肤浅的分析可能得出这样的结论：服务器端的Web开发局限于脚本语言，诸如PHP、Perl、Python（即流行的LAMP架构缩写中的“P”），或者基于Microsoft ASP（动态服务器页面）技术的.Net语言。对于小规模的Web开发可能确实如此，然而值得注意的是，许多大规模的Web服务器都使用C++实现的后台服务，以求最佳性能。
事实上，Facebook开发过一个名为HipHop的产品，它将PHP代码转换为C++，以此改善社交网站的性能。因此C++ API设计在可扩展的Web服务开发中确实占有一席之地。此外，使用C++开发核心API不仅可以构建高性能的Web服务，而且这些代码还可以在诸如桌面或移动电话版本等其他形式交付的产品中重用。
说句题外话，对于这种软件开发策略的转变，一种可能的解释是全球化推动的结果（Friedman，2008；Wolf， 2004）。实际上，互联网、标准网络协议和Web技术的汇聚已经创造了一个软件竞技平台。这使得来自世界各地的公司和个人都可以在大型复杂软件项目中进行创造、贡献和竞争。这种形式的全球化促成了一种环境，在该环境下，全世界的公司和开发者能够以开发软件子系统为生。世界各地的其他组织进而可以通过组合与扩展这些构建模块创建解决特定问题的最终用户应用程序。就本书讨论的焦点而言，API提供了促成现代软件开发全球化和组件化的机制。
即使你只是编写内部软件，与你共事的工程师也很可能要使用你的代码编辑程序。如果使用良好的API设计技巧，就可以简化彼此的工作，不必回答诸多关于代码如何工作、如何使用的问题。这在多个开发者并行开发相互依赖的代码时显得尤为重要。
举例来说，假设你正在编写一个字符串加密算法，其他开发者需要使用该算法将数据写入配置文件。一种做法是让其他开发者等你完成所有工作，然后在其文件输出模块中使用你的算法。然而，更有效率的做法是，你们提前见面协商好恰当的API，然后你把API放在适当的位置，而API仅仅起占位符的作用，这样你的同事就可以立即调用它们了，例如：
#include &string&
classStringEncryptor
///设置Encrypt()和Decrypt()调用时使用的密钥
voidSetKey(conststd::string &key);
///基于当前密钥加密输入字符串
std::string Encrypt(conststd::string &str)
///基于当前密钥解密输入字符串
/// Decrypt()一个由Encrypt()返回的字符串
/// 返回同一个密钥下原始的字符串
std::string Decrypt(conststd::string &str)
接着，你可以提供这些函数的简单实现，使得该模块至少可以编译和链接。例如，相关的.cpp文件可以像下面这样：
voidStringEncryptor::SetKey(conststd::string &key)
std::string StringEncryptor::Encrypt(conststd::string &str)
std::string StringEncryptor::Decrypt(conststd::string &str)
这样一来，你的同事就能够使用这个API继续工作而不被你的进度所耽搁。虽然目前你的API实际上不会加密任何字符串，但是这只是一个小的实现细节。重要的是已经有了一个双方都认可的稳定接口，即一个契约，而且该接口的行为恰当，例如Decrypt(Encrypt(&Hello&))将会返回“Hello”。当你完成了工作，并以正确的实现更新了.cpp文件后，你同事的那部分代码不需要进行任何修改就能直接运行了。
实际上，有些接口问题很可能在编写代码之前并没有预料到，因此API设计可能需要多次迭代才能保证其恰到好处。在大多数情况下，API支持双方能够以最少的停顿并行工作。
这种方法还用利于测试驱动或者是测试先行的开发。事先确定了API，就可以编写单元测试来验证预期的功能，并且可以持续运行这些测试程序，以保证始终没有打破你和同事之间的协议。
将该过程延伸到组织层面，你的项目可以有独立的团队，他们彼此也许相距很远，甚至遵循不同的日程安排。通过预先确定各个团队的依赖关系，并通过创建API来为这些关系建模，各个团队就可以独立工作，而几乎不必关心其他团队如何实现API背后的工作。资源的有效利用以及削减相应的冗余通信，能够为组织节约大量整体成本。
何时应当避免使用API
设计并实现API相比编写普通的应用程序代码通常要花费更多精力，因为API的宗旨是提供健壮、稳定的接口供其他开发人员使用。因此，与仅在单一应用程序内部使用的软件相比，API在质量、设计、文档编写、测试、支持及维护方面有更高的要求。
因此，如果编写的是不需要和其他客户端通信的内部模块，那么为模块创建并维护稳定公有接口的额外开销就不值得了，然而这并不是编写劣质代码的理由。为坚持API设计原则而多花费些时间，从长远看来并不浪费时间和精力。
另一方面，假设你是一位想在应用程序中使用第三方API的软件开发人员。前一节讨论了在软件中重用外部API的一些理由，但有时也可能需要避免使用特定的API，在如下这些情况下，你应该花精力自己实现代码或寻找替代的解决方案。
许可证限制。虽然API可以提供所需的各项精巧功能，但是许可证限制可能让你望而却步。例如，如果你想使用GNU GPL（General Public License，通用公共许可证）发布的开源包，那么就必须使用GPL发布所有衍生作品。如果在程序中使用这个包，就必须发布整个应用程序的源代码，这是商业应用可能不会接受的约束。其他的许可证（如GNU Lesser General License GPL，LGPL）就更加宽松些，在软件库中也更加常见。许可证问题的另一种体现是：商业API的费用对你的项目来说可能过于昂贵，或者许可条款可能过于严格，比如要求向每位开发者甚至每位用户收取许可费用。
功能不匹配。虽然API看似能够解决所面临的问题，但是它有可能以一种与应用程序约束或功能需求不匹配的方式执行。例如，可能你正在开发一个图像处理工具，想要提供傅里叶变换功能。虽然有许多现成的FFT（Fast Fourier Transform，快速傅里叶变换）的实现，但是其中大多数是1D算法，而处理2D图像数据需要使用2D FFT。此外，许多2D FFT算法只能在大小是2的整数幂的数据集上工作（如256×256或512 × 512）。或许你找到的API不能在必须支持的平台上运行，或者它不能满足你对程序制定的性能标准。
缺少源代码。虽然有许多开源API，但是有时符合要求的最佳API可能是闭源产品。也就是说，只提供接口的头文件，而背后的C++源文件并不同库一起发布。这有几项重要的影响，其中之一就是当库中存在错误时，不能通过检查源代码的方式定位问题。对于跟踪错误进而找到解决方案来说，阅读源代码是一个很重要的方法。
进一步说，不能访问API的源代码就丧失了通过修改源代码修复错误的能力。这意味着软件项目的进度可能会受到所使用的第三方API中不可预期问题的不利影响，并且需要等待该API的所有者处理你的错误报告并发布修复补丁。
缺乏文档。虽然API看似可以完全满足应用程序的需求，但是如果API的文档编写拙劣或根本没有文档，那么你最好再去寻找别的解决方案。在这种情况下，有可能是API的用法不清楚影响了它的使用，也有可能是你无法确定特定情况下API的行为，甚至可能是你根本无法信任那些连花点儿时间解释代码都做不到的开发者。
本文摘自即将上市的《C++ API设计》
人民邮电出版社信息技术分社市场部线上负责人
郭志敏 主要负责线上活动、书评
网店【当当、卓越、互动、京东】
社区维护【开源中国、CSDN、博客园、iteye等】
负责的官方微博：
个人新浪微博：
豆瓣小站：/107552/
我的豆瓣：/people/guozhimin/
豆瓣小组：/group/turingbook/
如何构建高效、健壮、稳定且可扩展的优质API？对于这一软件工程上的难题，Martin Reddy凭借长期的从业...API设计的基本要求
我的图书馆
API设计的基本要求
原文地址：/41233/背景目前互联网上充斥着大量的关于RESTful API（为方便，下文中“RESTful API ”简写为“API”）如何设计的文章，然而却没有一个”万能“的设计标准：如何鉴权？API 格式如何？你的API是否应该加入版本信息？当你开始写一个app的时候，特别是后端模型部分已经写完的时候，你不得不殚精竭虑的设计和实现自己app的public API部分。因为一旦发布，对外发布的API将会很难改变。在给SupportedFu设计API的时候，我试图以实用的角度来解决上面提到的问题。我希望可以设计出容易使用，容易部署，并且足够灵活的API，本文因此而生。&API设计的基本要求网上的很多关于API设计的观点都十分”学院派“，它们也许更有理论基础，但是有时却和现实世界脱轨（因此我是自由派）。所以我这篇文章的目标是从实践的角度出发，给出当前网络应用的API设计最佳实践（当然，是我认为的最佳了~），如果觉得不合适，我不会遵从标准。当然作为设计的基础，几个必须的原则还是要遵守的：需要强调的是：API的就是程序员的UI，和其他UI一样，你必须仔细考虑它的用户体验！&使用RESTful URLs 和action.虽然前面我说没有一个万能的API设计标准。但确实有一个被普遍承认和遵守：RESTfu设计原则。它被Roy Felding提出（在他的”基于网络的软件架构“论文中）。而REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作（GET ,POST,PUT,DELETE）。&那么我应该如何拆分出这些资源呢？显然从API用户的角度来看，”资源“应该是个名词。即使你的内部数据模型和资源已经有了很好的对应，API设计的时候你仍然不需要把它们一对一的都暴露出来。这里的关键是隐藏内部资源，暴露必需的外部资源。在SupportFu里，资源是 ticket、user、group。一旦定义好了要暴露的资源，你可以定义资源上允许的操作，以及这些操作和你的API的对应关系：可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里你只需要一个endpoint：/tickets,再没有其他什么命名规则和url规则了，cool！&这个endpoint的单数复数一个可以遵从的规则是：虽然看起来使用复数来描述某一个资源实例看起来别扭，但是统一所有的endpoint，使用复数使得你的URL更加规整。这让API使用者更加容易理解，对开发者来说也更容易实现。如何处理关联？关于如何处理资源之间的管理REST原则也有相关的描述：其中，如果这种关联和资源独立，那么我们可以在资源的输出表示中保存相应资源的endpoint。然后API的使用者就可以通过点击链接找到相关的资源。如果关联和资源联系紧密。资源的输出表示就应该直接保存相应资源信息。（例如这里如果message资源是独立存在的，那么上面 GET /tickets/12/messages就会返回相应message的链接；相反的如果message不独立存在，他和ticket依附存在，则上面的API调用返回直接返回message信息）不符合CURD的操作对这个令人困惑的问题，下面是一些解决方法：永远使用SSL毫无例外，永远都要使用SSL。你的应用不知道要被谁，以及什么情况访问。有些是安全的，有些不是。使用SSL可以减少鉴权的成本：你只需要一个简单的令牌（token）就可以鉴权了，而不是每次让用户对每次请求签名。值得注意的是：不要让非SSL的url访问重定向到SSL的url。&文档文档和API本身一样重要。文档应该容易找到，并且公开（把它们藏到pdf里面或者存到需要登录的地方都不太好）。文档应该有展示请求和输出的例子：或者以点击链接的方式或者通过curl的方式（请见openstack的文档）。如果有更新（特别是公开的API），应该及时更新文档。文档中应该有关于何时弃用某个API的时间表以及详情。使用邮件列表或者博客记录是好方法。&版本化在API上加入版本信息可以有效的防止用户访问已经更新了的API，同时也能让不同主要版本之间平稳过渡。关于是否将版本信息放入url还是放入请求头有过争论：. 学术界说它应该放到header里面去，但是如果放到url里面我们就可以跨版本的访问资源了。。（参考openstack）。strip使用的方法就很好：它的url里面有主版本信息，同时请求头俩面有子版本信息。这样在子版本变化过程中url的稳定的。变化有时是不可避免的，关键是如何管理变化。完整的文档和合理的时间表都会使得API使用者使用的更加轻松。&结果过滤，排序，搜索：url最好越简短越好，和结果过滤，排序，搜索相关的功能都应该通过参数实现(并且也很容易实现)。过滤：为所有提供过滤功能的接口提供统一的参数。例如：你想限制get /tickets 的返回结果:只返回那些open状态的ticket–get /tickektsstate=open这里的state就是过滤参数。排序：和过滤一样，一个好的排序参数应该能够描述排序规则，而不业务相关。复杂的排序规则应该通过组合实现：这里第二条查询中，排序规则有多个rule以逗号间隔组合而成。搜索：有些时候简单的排序是不够的。我们可以使用搜索技术（ElasticSearch和Lucene）来实现（依旧可以作为url的参数）。对于经常使用的搜索查询，我们可以为他们设立别名,这样会让API更加优雅。例如：get /ticketsq=recently_closed -& get /tickets/recently_closed.&限制API返回值的域有时候API使用者不需要所有的结果，在进行横向限制的时候（例如值返回API结果的前十项）还应该可以进行纵向限制。并且这个功能能有效的提高网络带宽使用率和速度。可以使用fields查询参数来限制返回的域例如：GET /ticketsfields=id,subject,customer_name,updated_at&state=open&sort=-updated_at&更新和创建操作应该返回资源PUT、POST、PATCH 操作在对资源进行操作的时候常常有一些副作用：例如created_at,updated_at 时间戳。为了防止用户多次的API调用（为了进行此次的更新操作），我们应该会返回更新的资源（updated representation.）例如：在POST操作以后，返回201 created 状态码，并且包含一个指向新资源的url作为返回头&是否需要 “HATEOAS“网上关于是否允许用户创建新的url有很大的异议（注意不是创建资源产生的url）。为此REST制定了HATEOAS来描述了和endpoint进行交互的时候，行为应该在资源的metadata返回值里面进行定义。（译注：作者这里认为HATEOAS还不算成熟，我也不怎么理解这段就算了，读者感兴趣可以自己去原文查看）&只提供json作为返回格式现在开始比较一下XML和json了。XML即冗长，难以阅读，又不适合各种编程语言解析。当然XML有扩展性的优势，但是如果你只是将它来对内部资源串行化，那么他的扩展优势也发挥不出来。很多应用（youtube,twitter,box）都已经开始抛弃XML了，我也不想多费口舌。给了google上的趋势图吧：当然如果的你使用用户里面企业用户居多，那么可能需要支持XML。如果是这样的话你还有另外一个问题：你的http请求中的media类型是应该和accept 头同步还是和url？为了方便（browser explorability）,应该是在url中(用户只要自己拼url就好了)。如果这样的话最好的方法是使用.xml或者.json的后缀。&命名方式？是蛇形命令（下划线和小写）还是驼峰命名？如果使用json那么最好的应该是遵守JAVASCRIPT的命名方法-也就是说骆驼命名法。如果你正在使用多种语言写一个库，那么最好按照那些语言所推荐的，java，c#使用骆驼，python，ruby使用snake。个人意见：我总觉得蛇形命令更好使一些，当然这没有什么理论的依据。有人说蛇形命名读起来更快，能达到20%，也不知道真假&默认使用pretty print格式，使用gzip只是使用空格的返回结果从浏览器上看总是觉得很恶心(一大坨有没有？～)。当然你可以提供url上的参数来控制使用“pretty print”，但是默认开启这个选项还是更加友好。格外的传输上的损失不会太大。相反你如果忘了使用gzip那么传输效率将会大大减少，损失大大增加。想象一个用户正在debug那么默认的输出就是可读的-而不用将结果拷贝到其他什么软件中在格式化-是想起来就很爽的事，不是么？下面是一个例子:$ curl /users/veesahni & with-whitespace.txt
$ ruby -r json -e 'puts JSON JSON.parse(STDIN.read)' & with-whitespace.txt & without-whitespace.txt
$ gzip -c with-whitespace.txt & with-whitespace.txt.gz
$ gzip -c without-whitespace.txt & without-whitespace.txt.gz输出如下：在上面的例子中，多余的空格使得结果大小多出了8.5%（没有使用gzip），相反只多出了2.6%。据说：twitter使用gzip之后它的streaming API传输减少了80%（link:/blog/announcing-gzip-compression-streaming-APIs）.&只在需要的时候使用“envelope”很多API象下面这样返回结果：123456{&&"data" : {&&&&"id" : 123,&&&&"name" : "John"&&}}理由很简单：这样做可以很容易扩展返回结果，你可以加入一些分页信息，一些数据的元信息等－这对于那些不容易访问到返回头的API使用者来说确实有用，但是随着“标准”的发展（cors和http://tools.ietf.org/html/rfc5988#page-6都开始被加入到标准中了），我个人推荐不要那么做。何时使用envelope？有两种情况是应该使用envelope的。如果API使用者确实无法访问返回头，或者API需要支持交叉域请求（通过jsonp）。jsonp请求在请求的url中包含了一个callback函数参数。如果给出了这个参数，那么API应该返回200，并且把真正的状态码放到返回值里面（包装在信封里），例如：1234567callback_function({&&status_code: 200,&&next_page: "https://..",&&response: {&&&&... actual JSON response body ... &&}})同样为了支持无法方法返回头的API使用者，可以允许envelope=true这样的参数。在post,put,patch上使用json作为输入如果你认同我上面说的，那么你应该决定使用json作为所有的API输出格式，那么我们接下来考虑考虑API的输入数据格式。很多的API使用url编码格式：就像是url查询参数的格式一样：单纯的键值对。这种方法简单有效，但是也有自己的问题：它没有数据类型的概念。这使得程序不得不根据字符串解析出布尔和整数,而且还没有层次结构–虽然有一些关于层次结构信息的约定存在可是和本身就支持层次结构的json比较一下还是不很好用。当然如果API本身就很简单，那么使用url格式的输入没什么问题。但对于复杂的API你应该使用json。或者干脆统一使用json。注意使用json传输的时候，要求请求头里面加入：Content-Type：application/json.，否则抛出415异常（unsupported media type）。&分页分页数据可以放到“信封”里面，但随着标准的改进，现在我推荐将分页信息放到link header里面：http://tools.ietf.org/html/rfc5988#page-6。使用link header的API应该返回一系列组合好了的url而不是让用户自己再去拼。这点在基于游标的分页中尤为重要。例如下面，来自github的文档12Link: &/user/repos?page=3&per_page=100&; rel="next", &/user/repos?page=50&per_page=100&; rel="last"自动加载相关的资源很多时候，自动加载相关资源非常有用，可以很大的提高效率。但是这却。为了如此，我们可以在url中添加参数：embed（或者expend）。embed可以是一个逗号分隔的串，例如：1GET /ticket/12embed=customer.name,assigned_user对应的API返回值如下：123456789101112{&&"id" : 12,&&"subject" : "I have a question!",&&"summary" : "Hi, ....",&&"customer" : {&&&&"name" : "Bob"&&},&&assigned_user: {&&&"id" : 42,&&&"name" : "Jim",&&}}值得提醒的是，这个功能有时候会很复杂，并且可能导致。&重写HTTP方法有的客户端只能发出简单的GET 和POST请求。为了照顾他们，我们可以重写HTTP请求。这里没有什么标准，但是一个普遍的方式是接受X-HTTP-Method-Override请求头。&速度限制为了避免请求泛滥，给API设置速度限制很重要。为此&&引入了HTTP状态码。加入速度设置之后，应该提示用户，至于如何提示标准上没有说明，不过流行的方法是使用HTTP的返回头。下面是几个必须的返回头（依照twitter的命名规则）：为什么使用当前时间段剩余秒数而不是时间戳？时间戳保存的信息很多，但是也包含了很多不必要的信息，用户只需要知道还剩几秒就可以再发请求了这样也避免了。有些API使用UNIX格式时间戳，我建议不要那么干。为什么？HTTP 已经规定了使用&&时间格式&鉴权&Authenticationrestful API是无状态的也就是说用户请求的鉴权和cookie以及session无关，每一次请求都应该包含鉴权证明。通过使用ssl我们可以不用每次都提供用户名和密码：我们可以给用户返回一个随机产生的token。这样可以极大的方便使用浏览器访问API的用户。这种方法适用于用户可以首先通过一次用户名-密码的验证并得到token，并且可以拷贝返回的token到以后的请求中。如果不方便，可以使用OAuth 2来进行token的安全传输。支持jsonp的API需要额外的鉴权方法，因为jsonp请求无法发送普通的credential。这种情况下可以在查询url中添加参数：access_token。注意使用url参数的问题是：目前大部分的网络服务器都会讲query参数保存到服务器日志中，这可能会成为大的安全风险。注意上面说到的只是三种传输token的方法，实际传输的token可能是一样的。&缓存HTTP提供了自带的缓存框架。你需要做的是在返回的时候加入一些返回头信息，在接受输入的时候加入输入验证。基本两种方法：ETag：当生成请求的时候，在HTTP头里面加入ETag，其中包含请求的校验和和哈希值，这个值和在输入变化的时候也应该变化。如果输入的HTTP请求包含IF-NONE-MATCH头以及一个ETag值，那么API应该返回304 not modified状态码，而不是常规的输出结果。Last-Modified：和etag一样，只是多了一个时间戳。返回头里的Last-Modified：包含了&&时间戳，它和IF-MODIFIED-SINCE一致。HTTP规范里面有三种date格式，服务器应该都能处理。出错处理就像html错误页面能够显示错误信息一样，API 也应该能返回可读的错误信息–它应该和一般的资源格式一致。API应该始终返回相应的状态码，以反映服务器或者请求的状态。API的错误码可以分为两部分，400系列和500系列，400系列表明客户端错误：如错误的请求格式等。500系列表示服务器错误。API应该至少将所有的400系列的错误以json形式返回。如果可能500系列的错误也应该如此。json格式的错误应该包含以下信息：一个有用的错误信息，一个唯一的错误码，以及任何可能的详细错误描述。如下：12345{&&"code" : 1234,&&"message" : "Something bad happened :-(",&&"description" : "More details about the error here"}对PUT,POST,PATCH的输入的校验也应该返回相应的错误信息，例如：12345678910111213141516{&&"code" : 1024,&&"message" : "Validation Failed",&&"errors" : [&&&&{&&&&&&"code" : 5432,&&&&&&"field" : "first_name",&&&&&&"message" : "First name cannot have fancy characters"&&&&},&&&&{&&&&&&&"code" : 5622,&&&&&&&"field" : "password",&&&&&&&"message" : "Password cannot be blank"&&&&}&&]}&HTTP 状态码123456789101112200 ok &- 成功返回状态，对应，GET,PUT,PATCH,DELETE.&201 created&&-&成功创建。&304 not modified &&-&HTTP缓存有效。&400 bad request &&-&请求格式错误。&401 unauthorized &&-&未授权。&403 forbidden &&-&鉴权成功，但是该用户没有权限。&404 not found - 请求的资源不存在&405 method not allowed - 该http方法不被允许。&410 gone - 这个url对应的资源现在不可用。&415 unsupported media type - 请求类型错误。&422 unprocessable entity - 校验错误时用。&429 too many request - 请求过多。&
TA的最新馆藏[转]&[转]&
喜欢该文的人也喜欢