日前岐岭OpenAPI网络平台正在进行v0.7.0版的研制，那个版他们期许导入API的图象，难道要折射API的功能结构设计，那具体而言要讲透API的结构设计准则，今天就想和我们谈谈，甚么样的API结构设计规则是最合适的。

他们拿自己原本晚期做的两个工程项目来做个悖论，这是那个工程项目的API图象

我们觉得有甚么难题？呢有那么几个：

两个controller好似相关联了很多正则表达式controller的中文名称和统计数据的名称没关系还有种统计数据叫shuchu？这是甚么鬼

细的而言，第一点和第一点是controller和model的中文名称不完全一致，app-controller（/app/xxx)用作DataAuth、Template等多种不同统计数据的输出，但是app那个中文名称并没天然资源涵义，所以app-controller和user-controller操作方式了太多的正则表达式。

那彼时为甚么那么结构设计呢，只不过只是即使那个工程项目是两个小流程的后台，所以后台合作开发的时候就直接使用了AppController那个英文名字，所以把所有的操作方式都放在了那个controller里头。

那他们后来碰到了甚么难题呢，具体而言就是保护繁杂，AppController越来越大，任何人两个严重错误的修正都要功能定位很久，其二是协同和沟通交流显得极度艰困，不论是奥尔杜省USB的后台还是中后期参予的其他合作开发，都极难认知标识符的销售业务方法论。

第一点在那个图的左面第五个统计数据，他的中文名称重新命名成了shuchu，彼时重新命名的惟一其原因是他是两个USB的输出正则表达式，这也是为甚么他们没错，一定是天然资源下定决心api，而不是api下定决心天然资源的其原因。他们具体而言需要确认的是api操作方式了哪四类天然资源，把天然资源按他的特性指示，再去下定决心api的中文名称，不能即使api导入了统计数据，就把统计数据单纯重新命名为ImportedData，或是像他们一样，即使输出了一种统计数据，就重新命名成了Shuchu。

所以这里也提醒所有的合作开发小伙伴，特别是像他们一样，小小厂的小伙伴

后台合作开发，先做统计数据天然资源结构设计，搞清楚所有天然资源后，再去堆标识符，做API结构设计，不着急！

后台结构设计的现代准则：RESTful

有了那么个悖论之后，那小伙伴肯定要问，那具体那个api结构设计有没甚么指导准则，毫无疑问的可以说，API在当今，最核心的结构设计理念就是RESTful，这是个2000年就提出来的概念，那个概念只不过是两个博士论文提出来的，维基百科说他是Roy Thomas Fielding博士于2000年在他的博士论文[1]中提出来的一种万维网软件架构风格。百度百科说他“首次出现在 2000 年 Roy Fielding 的博士论文中，Roy Fielding是 HTTP 规范的主要编写者之一”。

实际上，目前所有的API结构设计方法论，基本都是REST为基础结构的，而RESTful的基础要义，他们认为就是两个很单纯的准则：

URL及后台分层结构设计因以统计数据为导向，按统计数据进行分类，进行url、controller、service、mapper等多层结构设计

RESTful的API结构

为甚么那么说，看看维基百科的介绍（注意里头我加粗的字眼）

需要注意的是，REST是结构设计风格而不是

标准。REST通常基于HTTP、URI、XML以及HTML这些现有的广泛流行的协议和标准。

* 天然资源是由URI来指定。*

* 通过操作方式天然资源的表现形式来操作方式天然资源。

* 天然资源的表现形式则是XML或是HTML，取决于读者是机器还是人、是消费Web服务的客户软件还是Web浏览器。当然也可以是任何人其他的格式，例如JSON。

假设我合作开发了一个图书管应用，那个应用需要处理的对象有两种，两个是书（book），两个是书架（shelf），两个是借书人（user），那我最早接触Restful的ROR举例，rails指示可以创建3个controller，并自动的创建相关的函数，book的话，就会创建以下USB：

#获得所有图书 get /books => “books#index”, as => “books” #获得单个图书详情 get book/:id => “books#show”, as => “book” #打开创建图书页面 get /books/new => “books#new”, as => “new_book” #提交创建图书 post /books => “books#create”, as => “books” #打开编辑图书页面 get /books/:id/edit => “books#edit”, as => “edit_book” #更新两个具体的图书 put /book/:id => “book#update”, as => “book” #删除两个图书 delete /books/:id => “books#destroy”, as => “book”

其中，还有些单复数的USB区别，以便表征是操作方式多个还是单个，我记得ROR连一些特殊单词的复数也是正确的，person/people，man/men，有兴趣可以看那个：一篇文章讲那个单复数准则），这样的结构设计使得他们对于url的认知就很单纯了：

一套统一的url前缀表示一类天然资源：（上面都是/book…)新局部）。处理单个的，url中一定带id

那相关联的controller就会相关联7个函数，这七个函数的规范指示如下(后来还增加了UpdateMany和DeleteMany)

ReadMany ReadUpdate Delete New Create Edit

示意图如下：

RESTful的灵活处理准则

不需要一定是这7个函数

当然不是所有的API都可以完美的处理成RESTful的天然资源，他们经常碰到两个难题，登录到底要怎么结构设计，登录属于对User的Update么？还是属于Create？要是我要分别获得用户的头像、特性、级别、余额，我是在readUSB里用if-else分别处理这不同的统计数据返回么？

他们建议是

整体符合RESTful结构的url框架下，灵活处理繁杂类型

那上面那个例子而言，user他们就不处理成这其中函数了，而处理成

这样的controller结构，url的第一级仍然清楚的表明了是有关user的controller，同时，操作方式的入口也更为清楚。

不一定非要用put/patch

他们在应用RESTful的时候还碰到两个很大的难题，很多防火墙根本就不允许除了POST/GET之外的其他操作方式手段，如果非要用RESTful，RoR包括很多其他的框架支持通过query参数来指定方法，比如POST /book?METHOD=PUT会等效于PUT /book，这样的结构设计应用当然没难题，但是从USB的可阅读性上就查了好多，尤其在给甲方提交文档的时候，很多人会很不解，这种繁杂的模式的意义是甚么。我个人觉得也确实像脱了裤子FP。这种情况下就可以参考第一种例外模式来结构设计。

总结下来，那结构设计API的准则他们建议如下：

统计数据结构设计优于API结构设计，API结构设计为统计数据结构设计服务除部分公共统计数据之外，统计数据和API分组（Controller）最好一一相关联，一类API服务一类统计数据url准则，繁杂正则表达式再使用特殊模式

那他们如果真要结构设计两个能够清楚表明API结构设计优劣的图象的话，我觉得那个图至少要有这几个功能：

统计数据视图优先，可以展开统计数据和API的关系可以清楚的表示API Controller和统计数据的关系，是否有繁杂的1对N或交叉难题可以展开url的调用细节，以便查询RESTful的结构设计是否合理

这好难啊，好似现在的beta版还不行，他们尽力吧……