API的定义取决于选择的IPC通信方式,如果是消息机制（如 AMQP 或者 STOMP），API则由消息频道（channel）和消息类型；如果是使用HTTP机制，则是基于请求/响应（调用http的url），这里我们先简述下RestfulAPI的定义。
设计原则
域名
应该尽量将API部署在专用域名之下,如：
也可以放在主域名下：
版本
放入到头信息的Accept中
制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以，最好在设计之初就使用一些方法来预防可能会遇到的问题。
为了避免API的变动导致用户使用中产生意外结果或调用失败，最好强制要求所有访问都需要指定版本号。请避免提供默认版本号，一旦提供，日后想要修改它会相当困难。
最适合放置版本号的位置URL中，或者是头信息(HTTP Headers)中在 Accept 段中使用自定义类型(content type)与其他元数据(metadata)一起提交。
提供 Request-Id
为每一个请求响应包含一个Request-Id字段，并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值，它能主我们提供一种机制来跟踪、诊断和调试请求。
路径
资源名
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
行为（Actions）
好的末尾不需要为资源指定特殊的行为，但在特殊情况下，为某些资源指定行为却是必要的。为了描述清楚，在行为前加上一个标准的actions：
如：
路径和属性名
为了和域名命名规则保持一致，使用小写字母并用-分割路径名字，例如：
属性也使用小写字母，但是属性名要用下划线_分割，以便在Javascript中省略引号。 例如：
支持方便的无id间接引用
在某些情况下，让用户提供ID去定位资源是不方便的。例如，一个二手手游拍卖平台用户想取得他在Heroku平台app信息，但是这个app的唯一标识是UUID。这种情况下，你应该支持接口通过名字和ID都能访问，例如:
不要只接受使用名字而放弃了使用id。
最小化路径嵌套
在一些有父路径/子路径嵌套关系的资源数据模块中，路径可能有非常深的嵌套关系，例如:
推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中，dyno属于app，app属于org可以表示为：
HTTP动词
对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）：
一些例子：
过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
下面是一些常见的参数:
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
响应（Responses）
状态码
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）:
提供资源的(UU)ID
在默认情况给每一个资源一个id属性。除非有更好的理由，否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识，尤其是自动增长的id。
生成小写的UUID格式 8-4-4-4-12，例如：
提供标准的时间戳
为资源提供默认的创建时间 created_at 和更新时间 updated_at，例如:
使用UTC（世界标准时间）时间，用ISO8601进行格式化
在接收和返回时都只使用UTC格式(ISO8601格式的数据)或者使用时间戳。，例如:
或
错误处理
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范。
保证响应JSON及最小化
目前为保证响应最小化，一般使用json字符串，并且请求中多余的空格会增加响应大小，而且现在很多的HTTP客户端都会自己输出可读格式（"prettify"）的JSON。所以最好保证响应JSON最小化，例如：
而不是这样：
Hypermedia API
RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
比如，当用户向api.example的根目录发出请求，会得到这样一个文档。
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github会得到一个所有可用API的网址列表。
从上面可以看到，如果想获取当前用户的信息，应该去访问api.github/user，然后就得到了下面结果。
上面代码表示，服务器给出了提示信息，以及文档的网址。
分享自：
segmentfault/a/1190000008697972
