Web API 设计

web API 设计
开发者喜欢的精巧接口

先列出目录，内容后面慢慢的补上，敬请期待。。。

介绍

如果你正在阅读本文，对于你关心的设计出开发者喜欢的web api和你感兴趣的应用证明设计原则和最佳实践web api是个机会。

名词好；动词不好

第一个原则：让简单的事情简单。

基础URL要简单直观

基础URL是在API中最重要的。一个设计简单直观的基础URL会使你的api使用很简单。

每个资源应该只有2个基础URL。让我们用一个简单的对象或者资源比如狗模拟一个api。

第一个URL是一个集合，第二个是集合里的一个个体。

/dogs /dogs/1234

基础URL里不要包含动词

有些api会以方法函数形式来设计URL。这些URL里有时把动词放在开头，有时放在结尾。

不管是设计什么资源的api，你不要把一个对象认为成孤立的。他总是会和另一些资源有关系，像是他的主人，兽医，绳套，事物，松鼠等等。

在狗的世界里如果用动词做基础URL的话就会想下面的样子。

他就是个下坡路，很快你就会有一长串的URL和不一致的模式使开发者学习怎么使用你的api变得困难。

使用HTTP协议的动词去操作集合和元素。

对于我的狗资源来说，我们使用名词作为标签的2个基础URL，我们用HTTP动词操作他们。HTTP动词包括POST，GET，PUT，和DELETE。我认为他们对应增删改查操作。

用我们的2个资源和4个HTTP动词，我们可以给开发者提供大量的直观的api。如下图。

这样，开发者基本上不用看文档就能理解api的意思。

总结：

每个资源使用2个基础URL。

基础URL里不要出现动词。

使用HTTP动词去操作集合和元素。

复数名词和具体名称

让我们看下如何为你的URL挑选名词。

你应该用单数名词和复数名词？你会发现很多api是2种都在用。让我们看下例子。

考虑到大多数人可能用到的是api 的GET，我觉得使用复数名词阅读更加简单使用更加直观。但是，避免出现混合模型一些资源要用单数名词。同样，允许开发者预测和猜其方法调用，因为他们学会使用你的api。

具体名比抽象的好

实现纯抽象有时是api架构的目标。然而对开发者来说抽象不总是有意义的。

举个例子，API访问内容以各种形式——博客、视频、新闻、文章等等。

如果1个api使用高等级抽象像/items,/assets在我们的例子中，那么开发者在使用这样的api时，将失去画具体画内容的机会。让资源想播客，视频，新闻，新文章这样展示更有吸引力更有用。

抽象的等级根据你的情况而定。你还想暴露一个可管理的资源数量。以具体命名为目标，保持资源数在12-24之间。

总的来说，一个直观的api用复数名词而不是单数，用具体的而不是抽象的。

简化关联-除去？后面的复杂的东西

在这一部分，我们探索什么时候操作资源和参数或者说是声明和属性的关联。

关联

资源大多数和其他资源有关系。在web api里表达这种关系用什么简单的方法呢？

让我们看下之前在名词好，动词不好里面用到的关于狗的api。记住我们有2个基础Url:/dogs和/dogs/1234。

我们使用HTTP动词去操作他。我们的狗属于主人。为了让所有的狗都属于1个特定的主人，或者为主人创造1个新狗，要用GET和POST：

GET：/owners/5678/dogs

POST:/owners/5678/dogs

现在这种关系变得复杂了。主人和兽医也有关系，这个兽医和狗还有关系，狗和食物还有关系等等。不难看出，人们把这些用一个Url串起来要5-6个等级深。记住，一旦你在一个等级上有了主键，你通常不需要包括这个等级之上的的东西，因为你已经有了特定的对象。换句话说，当Url的深度大于我们等级/resource/identifier/resource之上的，我们不需要拥有太多的情况。

消除问号后面的复杂性

许多api在基础Url之上都很复杂。复杂不但包括许多声明可以被更新，改变和查询，而且属性和资源有关系。

在HTTP问号后使用可选的声明和属性让开发者使用更简单。想获取所有红色的狗在公园里跑：

GET /dogs?color=red&state=running&location=park

总结，简化资源之间的关系可以是api更直观，消除HTTP问号后的参数和复杂度。

操作错误

许多软件开发者，包括我本人，不喜欢总考虑异常处理和错误处理，但是他对于软件开发者来说确实是个难题，特别是对api设计者。

为什么好的错误设计对api设计者特别重要？

从开发人员角度来看你的api，任何事情从另一面看接口是个黑盒。错误为让你使用api提供来龙去脉和可视性。

首先，开发者通过错误写代码。极限编程模式是测试优先的概念和最新的测试驱动开发模式代表最佳实践。因为这样是对开发者更重要更自然的工作方法。

其次，当开发者用错误设计良好的api时，他们更容易根据出错提示解决问题。

如何用实际的方式思考错误

关于版本控制的小技巧

分页和部分响应

关于不要把资源卷入进来的回答

支持多种格式

属性名字应该是怎么样的

关于检索的小技巧

在一个子域里巩固api 请求

异常处理行为的小技巧

认证

发送api请求

口语化的api

用一个sdk做补充

api的外观模式