RESTful API总结

误区

使用restful的api设计，对于springmvc进行api定义不是很方便？

例如，设计一个查询一个应用下面某个订单号信息的api
假如使用传统的url设计思路

http://www.example.com/order?appKey=adsds&orderId=2434545

对应要写的mapping方法为

@GetMapping("order")
    public Order getOrder(OrderPararm param) {

        ....
        return result;
    }

OrderParam

@Data
public class OrderParam{
    private String orderId;
    private String appKey;
}

Restful的api设计

http://www.example.com/order/{app_key}/{order_id}

对应要写的mapping方法为

@GetMapping("order/{appKey}/{orderId}")
    public Order getOrder(@PathVariable String appKey,@PathVariable String orderId) {

        ....
        return result;
    }

这两者最大的区别就是，restful的api接受到请求，要使用@PathVariable从url中解析出资源参数，而传统的方式只要使用一个OrderParam，将声明的参数定义在模型中即可。

虽然使用restful不能使用同一的模型接收参数，但是restful的方式还是有它的好处的。

1. 资源参数放在url中，可以同一在拦截器做些业务逻辑。例如要针对某些用户限制api的调用频率。
2. 可以验证资源的正确性，例如验证订单号是否是属于这个应用的。
3. Restful的url规范了资源参数只在url中，在上游业务可以而外做些业务，例如在nginx中做些业务，如果使用传统的api设计，传递的参数并没有很规范（客户端可能没有传参数，或者参数写在url后面或者使用body来传），上游业务不是很好处理

虽然有点编码上的不方便（不能使用一个pojo来接收全部请求参数），但是还是建议使用RestFul的api设计。

使用了restful的api设计，就没有必要使用传统的“?”+参数的方式进行传参了

restful的api设计，本质是对请求参数进行区分，分成资源定义参数及限制参数。将用于表示资源的参数放在url中，而用于限制查询结果的参数还是通过请求字符串的方式进行传递
例如，查询一个应用下面的某段时间的订单列表

http://www.example.com/order/{app_key}?stime=2017-01-01&etime=2017-08-06

stime,etime不应该是一个url的组成路径，而应该是限制参数，这样更符合restful的设计思想。
Restful的api一般来讲就是用http请求头中的url和http method来标识一个资源。
相对于传统的http请求，restful风格的请求更直观的表示请求资源。