本系列的前两篇讨论了目标的重要以及消费者这两个对API设计至关重要的因素。这些因素均强调了上下文对于设计的重要性。上下文可能影响其中的技术或暴露的信息范围。

一旦API的上下文一经建立，开始认真考虑细节的时间就到了。这又被分为两个独立的部分，即读操作和写操作，因为服务组合的大多数都是读操作，无论是暴露的操作的数量还是调用的数量均如此。写功能应该最小化，只有一种让更新发生的方式会比较好。

读这一块，必须牢记灵活性问题。作为开发者，一想到读信息时你会想到什么？SQL。看看现在的服务调用技术，提供查询灵活性很大程度上是设计的事。SOAP自己并不提供功能性结构，只有设计结构的机制。REST，在通过HTTP来应用时，至少要依赖HTTP的动词和URL结构，因此GET和查询参数可以用上。尽管那提供了一些框架，但仍然有更多的设计工作要做。

从名词开始

第一部是从名词开始。无论你是用REST、SOAP、XML或者JSON都是是如此。用REST时会有动词“GET”。用SOAP时会有一项“get XYZ”形式的操作。不要担心这些动词；把注意力集中在名词以及它们的结构上。REST调用这些名词资源。SOAP，回到SOAP还是缩略词的时候，把这些名词叫做对象（object）。就我们的目的而言，这可以被称为资源模型。资源模型需要设计为表示通过API查询出来的被暴露的信息。这是一种信息建模的做法。并不意味着可以用取出一个逻辑数据库模型然后通过代码生成器及结果公布的API运行。数据库也许会出于其他目的被优化过，也可能会有动态生成的值。最重要的是，SOA的最佳实践应该得到遵循，API应该用来体现适当的抽象层。

信息量可以非常吓人，尤其是那些内部API的信息量。D. Keith Casey, Jr. 与James Higginbotham在《API设计实践指南》一书中提供了这种资源模型的使用指导。他们建议为资源建立一个简单的分类表，可分为独立（可完全依靠自己）、依赖（只有在其他资源的上下文中才相关）或关联（需要信息描述两个资源之间的关系）。

一旦做出了一个资源模型，下一个决定就是如何展现这一信息模型。采用HTTP GET加上JSON响应的RESTful方法是最流行的技术。然而，决定并未到此结束。对HTTP GET的调用会返回一个简单资源或一组资源。但是如果返回的资源含依赖资源的话，这些依赖资源是否也应该返回呢？还是说应该返回其链接？如果该资源有大量的属性又该怎么办？整个资源能否填充进去？如果不能的话，消费者会不会指定自己需要什么信息？对于这些可以考虑像OData或JAX-RS这样的规范，这也是一个需要考虑工具化的领域。

记住，框架和工具化并不能取代设计工作，这一点也很重要。如果可以的话，就不需要文章和书籍去介绍这方面的东西了。至于应该暴露多少数据的决策问题，可考虑以下一些东西：

服务变更的频率有多频繁？如果所有数据并未在消费者需要某个无法访问的东西时曝光（至少在内部），那么服务变更就是必要的。也许最好是在底层数据来源改变时变更查询服务，而不是消费者改变时变更。

获取任何比例的数据会不会存在性能相关的问题？比方说，从数据库返回另一列往往不会影响性能。而执行与另一个表的连接则会产生更大的影响。

消费者应该有多大的灵活性？允许他们询问究竟想要什么与从某些预定义集合中选择之间需要有所权衡。预定义集合实现起来更快，且能提供一层保护避免消费者的行为不端。然而，其需要考虑的权衡是如果预定义集合不能充分覆盖用例情况的话，变更请求就会一波接着一波。如果需要灵活性最大化，那实现起来就会更加复杂，将某些形势的查询语言转化为对数据来源合适的调用，应用防御性语言确保灵活性不会置数据系统的稳定性及完整性于危险之地。

本文80%的篇幅讨论的都是查询端API的设计，这么做事出有因，因为80%的API可能都是与支持查询有关。另20%将会谈谈允许消费者请求采取行动的API。这里的东西可能会引起一些争议。

别忘了动词

除了GET以外，HTTP的动词世界还包括PUT、POST和DELETE。几乎信息系统的一切都是与创建、读取、更新和删除有关，尽管这话没错，但是这并非用来描述业务流程的唯一动词。这些可以归结为PUT和POST。

SOAP把所有东西都往POST请求里面放的原因只有一个：这么做更灵活。在一个场景的电子商务场景中，有人用过动词POST吗？没有，他们用的是购买、支付、结账。这会导致RESTful方案看起来糟糕吗？当然也不会。这只是开发者意味着要想严格遵守规则的话，就需要理解购买东西、发送包裹或进行任何形式的业务时需要PUT或POST什么。REST的东西，如对其他资源的链接等依然重要，也应该成为API的一部分。

无论理解目标需要花费多少时间，只要了解消费者并想出完美的资源模型，情况就会发生变化。本系列的最后一篇文章就将会谈版本控制并提供管理工具在设计API是可扮演的额外角色的相关细节。