你的位置:首页 > ASP.net教程

[ASP.net教程]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.1X-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.1X-Auth-Timestamp: Mon, 26 Mar 2007 19:37:58 +0000Authorization: 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