【Web Design The Missing Link】Introduction

根据定义，Web API使用HTTP。 在Web_API的早期，人们花费大量时间和精力来弄清楚如何在HTTP之上实现CORBA和DCOM等上一代分布式技术的功能。 这导致了诸如SOAP和WSDL之类的技术。经验表明，与大多数Web API相比，这些技术更复杂，更重且更易碎。取代SOAP和WSDL的想法是，您可以更直接地使用HTTP，而减少对上层技术的运用。 大多数现代Web API都比SOAP或WSDL_API简单得多，但是保留了一些远程过程调用的基本思想（这不是HTTP固有的），并且在HTTP上的实现要轻得多。这些API已被称为RESTful_API。在Apigee，我们提倡您应尽可能只使用HTTP而无其他概念。

 

---

原因

---

在设计任何接口时，您都应该把自己摆在用户的位置。作为API提供者，您可能使用单个或一小组API，但是您的用户可能会处理比您更多的API。这意味着他们很可能对基本的HTTP技术和标准以及其他API有深入的了解。因此，遵守标准和既定惯例比发明自己的标准规范更具有价值。 HTTP规范是业界见过的写得最好，设计最好和最普遍接受的标准，因此，您能发明一种可以更好地为用户服务的替代方案的机会很小。并非所有用户都对HTTP标准有详细的了解，但是，让他们学习使用API标准的HTTP机制对于他们和您而言，比向他们教授您发明的替代方案是更好的选择。

 

例如，如果您的API使用POST创建资源，请确保在响应中包括一个Location标头，其中包括新创建的资源的URL以及201状态代码（这是HTTP标准的一部分）。 如果您需要检查两个人没有尝试同时更新同一网络资源，请使用ETag和If-Match标头，这也是HTTP标准。 如果您的API允许用户请求其他格式的数据，请使用HTTP接受标头。

 

如果您想提供特定于API的标准机制的替代方法，请继续，但是除了支持标准机制外，还请这样做。 做到所有这些，您的用户，尤其是那些对网络的运行情况了解并且对其他API经验丰富的用户，将非常感谢您。

 

本书是我们与全球一些领先的API团队合作开发的设计实践的集合。 无论您是同意，不同意还是要分享一些其他Web API设计最佳做法和技巧，我们都希望收到您的反馈。 Apigee社区中的API设计小组是Web API设计爱好者聚集在一起共享和辩论设计实践的地方。 我们希望在那里见到您。