本系列前两篇：
上一篇我们聊过了确认开放平台的服务范围和接口的设计，本篇我们讨论的是接口契约的设计，就是每个接口所包含的字段。有人觉得契约设计是开发人员的职责，其实不然，开发人员（特别是没有产品思维的开发人员）设计契约有几个弊端：1. 包含大量非业务字段，致使契约非常复杂；2. 接口名称字段命名不规范；3. 字段描述偏技术化和公司化，非技术人员或非本公司员工基本无法理解，比如在携程有“可选项”这个名词，如果没在携程干过估计完全无法理解。造成上面这种情况的原因是开发人员对数据库太熟了，所以设计的契约就沿用了数据库的结构和字段名称。
实际上契约设计直接反映了产品经理对业务的理解程度，需要隐藏部分内部流程和技术上的字段，以免给开发者和用户造成困扰，同时不能遗漏重要字段，需要站在第三方开发者和用户的角度去考虑各种场景，提供最适合的契约。
契约是整个平台设计中非常重要的部分，因为围绕平台开发的大部分时间都需要面对着契约，好的契约设计能让开发者一目了然的知道接口的用处和各字段的含义，而一个不好的设计会让开发摸不到头脑，不得不询问技术支持或者频繁的测试才能完成接口的开发。
1. 接口的命名
首先需要考虑的是接口的名称，好的名称是可以自解释的，看了名字就知道这个接口的用途了。比如taobao.product.add这个接口名称，一看就知道是添加产品接口。再看看苏宁的suning.custom.shelves.move接口，这个乍一看就不知道是干啥的，看了接口名称“商品下架”才发现，本意应该是remove的意思，另外下架一般使用的动词是delisting。
在命名时最好遵循通用的规则，这样可以降低开发人员学习的成本。我列举几个常用的接口动词：
部分动作对应多于一个的动词，比如新增对应了add和create，但是一套系统中只能选择一个，不要两个都出现。同时尽量避免一套接口在同一个行为下使用不同的动词，比如淘宝开放平台中获得批量结果的接口有的用search，有的用list，这样可能会造成开发者的混淆。
还有就是外面提的比较多的Restful API风格，使用的是Http的动词来表示增删改查这几个动作，目前来看还没有开放平台完全采用这种规则的，当然Restful API风格还是有很多可取之处的，有兴趣可以查看这边文章：RESTful API 设计指南。
2. 参数传递格式
说完接口名称，我们在看看参数的传递方式。主流的有两种，一种是组装成指定的格式（一般为json或xml格式）直接post到指定的接口地址，苏宁开放平台就属于这种。另外一种方式是key/value的方式，即key1=value1&key2=value2&...，淘宝开放平台使用的是这种方式。比如淘宝的查询商品信息接口taobao.product.get中的请求参数有product_id、method和fields，那么他的请求url可以是http://gw.api.tbsandbox.com/router/rest?method=taobao.product.get&product_id=5289542&fields=product_id（仅为示例，去掉了部分参数）。这种方式对于参数比较简单的接口非常实用，甚至可以直接在浏览器中请求。上面这两种方式无所谓优劣，对于开发者来说应该都是比较容易理解和掌握的。
对于返回参数的格式，基本都比较统一，几乎都支持json和xml两种格式，开发者可以根据自己的使用习惯进行选择。
3. 契约字段的层级
所谓字段的层级是契约字段离根节点的级数。淘宝开放平台的字段层级基本都是1，也就是说基本都是根节点这种类似于key/value的形式。例如taobao.product.get接口的应用及输入参数：
这种结构容易理解，缺点是对于表示复杂的参数类型时需要自定义结构类型。比如上面的customer_props参数，它其实是一个复杂的类型，里面有多个属性和属性的值，但是由于这种结构的制约，无法做成强类型，只能采用这种pid1:value1;pid2:value2格式。
我们再看个极端的例子，下面是携程团队游开放平台的添加产品信息契约：
受限于旅游行业的复杂性和携程对商品信息的严苛要求，最终设计了这样的请求报文格式，最大的字段层级高达5级。这样一个复杂的结构如果不在商品内容上做出妥协几乎是不可能用key/value的形式表现出来的。
对于报文的层级这里并不推荐我们携程团队游的做法，开发者接受这样的复杂结构还是有一定难度的。对于key/value形式实在表示不了的，建议将value扩展为json格式，达到表示复杂结构的目的。
4. 字段的命名
最后关于字段的命名有两点需要注意：1.命名要统一，如果商品命名为product，就不要在另一个字段中用item或sales来表示商品。2.不要出现拼写错误，不要出现拼写错误，不要出现拼写错误。（重要的事情说三遍）
下集预告：授权系统。
作者：有bigger的产品狗
博客：http://www.jianshu.com/users/63e14c8782f2/latest_articles
本文版权归作者和简书共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。
网友评论