REST API注意事项

RFC一致性

Methods

GET: 获取某个资源，幂等且无副作用。

POST: 创建一个新的资源。

PUT: 替换某个已有的资源。幂等有副作用。

PATCH: 修改某个已有的资源。

DELETE：删除某个资源。幂等有副作用。

Headers

Accept：服务器需要返回什么样的content。

If-Modified-Since/If-None-Match：如果客户端提供某个条件，那么当这条件满足时，才返回数据，否则返回304 not modified。

If-Match：在对某个资源做PUT/PATCH/DELETE操作时，服务器应该要求客户端提供If-Match头，只有客户端提供的Etag与服务器对应资源的Etag一致，才进行操作，否则返回412 precondition failed。

返回恰当的Status Code

安全性

一致性，机密性，和可用性

请求数据验证

Request headers是否合法：如果出现了某些不该有的头，或者某些必须包含的头没有出现或者内容不合法，根据其错误类型一律返回4xx。
可以在HTTP头中增加X-Request-ID标识调用者身份。
示例：

GET /photos/puppy.jpg HTTP/1.1
X-Request-ID: 1pvs6edg31p92bld853plok8b4

Request URI和Request body是否合法：如果请求带有了不该有的数据，或者某些必须包含的数据没有出现或内容不合法，一律返回4xx。

数据完整性验证

数据完整性验证的底线是：保证要修改的数据和服务器里的数据是一致的 —— 这是通过Etag来完成。
Etag可以认为是某个资源的一个唯一的版本号。当客户端请求某个资源时，该资源的Etag一同被返回，而当客户端需要修改该资源时，需要通过"If-Match"头来提供这个Etag。
服务器检查客户端提供的Etag是否和服务器同一资源的Etag相同，如果相同，才进行修改，否则返回412 precondition failed。

访问控制

REST API需要清晰定义哪些操作能够公开访问，哪些操作需要授权访问。

在HTTP协议之上处理授权有很多方法，如HTTP BASIC Auth，OAuth，HMAC Auth等，其核心思想都是验证某个请求是由一个合法的请求者发起。

HMAC Auth保证一致性：请求的数据在传输过程中未被修改，因此可以安全地用于验证请求的合法性。
HMAC主要在请求头中使用两个字段：Authorization和Date（或X-Auth-Timestamp）。
Authorization字段的内容由":"分隔成两部分，":"前是access-key，":"后是HTTP请求的HMAC值。 在做HMAC的时候，request headers中的request method，request URI，Date/X-Auth-Timestamp等header会被计算在HMAC中。
示例：

GET /photos/puppy.jpg HTTP/1.1
X-Auth-Timestamp: Mon, 26 Mar 2007 19:37:58 +0000
Authorization: AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg=

将时间戳计算在HMAC中的好处是可以防止replay攻击。一个请求携带的时间戳，和该请求到达服务器时服务器的时间戳，中间差别太大，超过某个阈值（比如说120s），那么可以认为是replay，服务器主动丢弃该请求。

需要保证传输内容安全，使用HTTPS加密传输。

其他

rate limiting：访问限制。

metrics：服务器应该收集每个请求的访问时间，到达时间，处理时间，latency，便于了解API的性能和客户端的访问分布，以便更好地优化性能和应对突发请求。

docs：丰富的接口文档 —— API的调用者需要详尽的文档来正确调用API，可以用swagger来实现。

hooks/event propogation：其他系统能够比较方便地与该API集成。

参考文章：http://kb.cnblogs.com/page/521718/
作者: programmer_life