restful接口的设计细节

起

restful接口在日常web编程中非常频繁，大家在写restful 接口时，总结出那些规则呢？先开始SHOW我的总结吧——

转

1. 资源接口
   常规的资源接口，如下——

   /<resource>/
       GET - list
       POST - create
   /<resource>/<pk>/
       GET
       PATCH - partial_update
       POST - update
       DELETE - destroy
       ...
   

   资源名作为前缀，无索引PK的接口作为创建和列表接口，有索引PK的作为资源操作接口。
   资源操作非常优雅。但是隐式接口在应对复杂功能比较晦涩而且扩展困难。
2. 功能接口

       /<resource>/create/
       /<resource>/list/
       /<resource>/<pk>/update/
       /<resource>/<pk>/destroy/
   

   资源名作为前缀, 后面是功能或者缩影pk。
   声明式显示动作，常用格式。
3. 特定业务定制

       /<business>/<resource>/<pk>/destroy/
   

   把明确的业务名，作为前缀扩展，后续扩展的时候会看到这个前缀，防止扩展时未考虑到该业务，出现回归BUG。

承

接口格式无优劣，适合的才是最好的。

合

个人通用规范 - 以资源接口为主，扩展功能接口，不排斥业务接口。
个人喜欢/结尾URL，混合资源和功能接口，不会把版本作为URL的一部分。

/<namespace>/<resource_or_function>/<pk_or_action>/
    /default/model/1/           // 访问 model 1
    /default/model/page/        // 访问 model 分页列表（个人喜欢把 page + list 分开，而不是通过参数隐式控制）
    /default/model/list/        // 访问 model 总列表
    
    ...
/<namespace>/<resource_or_function>/<pk_or_action>/<subresource_or_subaction>/
    /default/model/1/goto/              // 访问 model(1) goto 功能
    /default/model/name/hello/          // 访问通过 name 关键词过滤出 name=hello 的资源 model
    /default/model/1/submodel/page/             // 有层级关系的资源访问
    /default/model/type/hot/submodel/page/      // 有层级关系的资源访问 - 2

多编码，多思考，生活愉快！