接口开发建议（draft） - PuZheng/PuZheng-Docs GitHub Wiki

引子

这里我们假设数据传输格式是JSON， 接口都围绕着该对象：

class Person(object):
    
    def __init__(self, name, age, gender, email, favorite_color):
        self.name = name
        self.age = age
        self.favorite_color = favorite_color

遵守RESTFUL风格

除了POST操作, 尽量保证接口幂等

幂等参考idempotence-in-http.　 这一条其实是RESTFUL中要求的， 但是因为极其重要，而且不被人重视，所以单独拿出来说明。 只有实现了这一条，才能验证两个接口在语义上的兼容性。比如：

PUT /site1/person/1/age=55?__verbose__=1
PUT /site2/person/1/age=55?__verbose__=1

*__verbose__*参数请参考附属建议。 如果这两个接口返回的数据相同，　那么就可以判定这两个接口语义上是兼容的, 而不单单是语法兼容。

URL参数， 传输的数据遵从一种命名方式， 或者是camel case或者unix style， 例如：

GET /person-list?sortBy=email&field=name,favoriteColor

返回数据应当是:

[
    {
        "name": "James T Kirk",
        "age": 43,
        "favoriteColor": "yellow",
    }
    
]

因为这里都采用了camel case。

用dict表示对象， 用list表示一组同类对象。

有些javascript背景的程序员在设计接口的时候，可能喜欢用一个list表示一个对象， 例如：

["James T. Kirk", 43, "yellow"]

来表示一个Person对象， 一定不要这样做，对方不好理解你的接口. 如果在同一个数组中的对象，默认就是同一种对象，拿面向对象的说法就是：他们有共同的类或者基类。

如果同一对象出现在不同的接口中， 那么表现形式一定要相似。 这里相似的定义是：

• 对于同时出现的属性， 那么键值名称，　数据类型一定要相同。
• 没有特殊的理由，　尽量保证一个对象的表现形式相同。即使某个属性值为空，　返回NULL或者默认值。

附属建议

针对修改型接口，　例如PUT, POST等操作，　接口支持一个特殊参数，　当这个特殊参数SET的时候，　返回操作的详细结果。　例如：

PUT /person/1?age=55&__verbose__=1

这里的*__verbose__*就是该特殊参数。　 返回的数据可以为

{
    "msg": "success",
    "result": {
        "age": 55
    }
}

而操作

POST /person?name=Picard&age=57&favoriteColor=yellow&__verbose__=1

返回的数据可以为：

{
    "msg": "success",
    "result": {
        "name": "Picard",
        "age": 44,
        "favoriteColor": "yellow",
    }
}

这样会极大的方便编写自动化测试脚本，　以及自动验证接口兼容性。