处理REST API中的标志和属性有哪些选项？

Question

假设您在REST API中有一个复杂的资源.您在此资源上有几个一对多的标记和属性(即,用户可能已将资源评级为1到5,或者用户可能"喜欢"该资源或将其标记为垃圾邮件或忽略它或导致其他一些状态待定).

关于在以资源为中心的架构中表示这一点的最佳方式已经提出了一些建议,但到目前为止,它们都没有真正让我开心.所以让我们来源吧; 您觉得哪种变体最容易理解？我们没想过哪些变种？假设基于OAuth的API,此处的所有内容都是在当前授权用户的上下文中完成的.

• 布尔标志

  • 变式1:

    GET /resource/{id}/muted
    POST /resource/{id}/muted BODY:true
    POST /resource/{id}/muted BODY:false
    

  • 变式2:

    GET /resource/{id}/muted
    PUT /resource/{id}/muted BODY:true
    DELETE /resource/{id}/muted
    

  • 变式3:

    GET /resource/{id}/attributes
    POST /resource/{id}/attributes BODY:muted=true
    POST /resource/{id}/attributes BODY:muted=false
    

  • 变式4:

    GET /resource/{id}/muted
    POST /resource/{id}/mute
    POST /resource/{id}/unmute
    

• 属性

  • 变式1

    GET /resource/{id}/rating
    POST /resource/{id}/rating BODY:4
    

  • 变式2:

    GET /resource/{id}/rating
    PUT /resource/{id}/rating BODY:4
    DELETE /resource/{id}/rating
    

  • 变式3:

    GET /resource/{id}/attributes
    POST /resource/{id}/attributes BODY:rating=4
    POST /resource/{id}/attributes BODY:rating=
    

思考？建议？其他API如何处理这个？你是怎么处理的？您是否发现这样的设计问题对开发人员的快乐或API的易用性产生了重大影响？

Answer 1

来自Roy的论文:

统一的界面会降低效率,因为信息是以标准化形式传输的,而不是特定于应用程序需求的形式.REST接口旨在高效地进行大粒度超媒体数据传输

所以你需要一个适用于标志和其他属性的变体5:

GET /resource/{id}/  BODY:{muted: false, like: false, rating: 2, ignored: true}
POST /resource/{id}/ BODY:{muted: true, like: false, rating: 2, ignored: true}
POST /resource/{id}/ BODY:{muted: false, like: false, rating: 2, ignored: true}

一个重要原因是RESTful HTTP应用程序的大部分效率来自缓存,并且当其工件尽可能大,并且其数据可以尽可能少的标识符访问时,效果最佳.如果你在两个揭露"静音"标志/resource/{id}/和/resource/{id}/muted,那么你有一个缓存失效的问题.如果你只暴露它/resource/{id}/,那么你不会.

如果您正在设计一个旨在通过小型有效负载实现效率的应用程序,那么您无法从大型粒度缓存中受益,并且REST架构风格不适合您的应用程序.HTTP可能也不是,但我可以理解在今天的市场中有人可能会如何坚持.