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

Question

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

关于在以资源为中心的架构中表示这一点的最佳方式，已经提出了一些建议，但到目前为止，没有一个真正让我满意。因此，让我们众包这个；您发现哪些变体最容易理解？我们没有想到哪些变体？假设有一个基于 OAuth 的 API，这里的一切都是在当前授权用户的上下文中完成的。

• bool 标志

  • 变体 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's dissertation :

a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs. The REST interface is designed to be efficient for large-grain hypermedia data transfer

因此您需要一个适用于标志和其他属性的变体 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 中都公开了“muted”标志，那么您就会遇到缓存失效问题。如果你只在 /resource/{id}/ 公开它，那么你就不会。

如果您设计的应用程序旨在通过小负载提高效率，那么您将无法从大粒度缓存中获益，并且 REST 架构风格不适合您的应用程序。 HTTP 可能也不是，但我能理解在当今市场上有些人可能会坚持使用它。