json - 这种 RESTful JSON 响应格式是否符合 HATEOAS？

Question

在工作中使用 REST API 时，遇到了一个问题，我想传递一个表示关系的值以及该关系的 URL，以便它可以与 HATEOAS 兼容。

我想我已经想出了一个合适的解决方案，但希望得到比我知识更多的人的确认。

此 RESTful JSON 响应是否仍符合 HATEOAS 原则？

{
  "employee":{
      "empId":12345,
      "fName":"Bubba",
      "lName":"Gump",
      "title":"Shrimp",
      "reportsTo":54321,
      "hateoas":{
          "self":"http://www.bubbagumpshrimp.com/rest/Employees/12345",
          "reportsTo":"http://www.bubbagumpshrimp.com/rest/Employees/54321",
          "directReports":"http://www.bubbagumpshrimp.com/rest/Employees/?reportsTo=12345"
      }
  }
}

那么大家怎么看呢？这种格式行得通吗？

根据下面@fumanchu 的建议，这是我现在要尝试使用的格式...

{
    "employee":{
        "empId":12345,
        "fName":"Bubba",
        "lName":"Gump",
        "title":"Shrimp",
        "reportsTo":54321,
        "hateoas":{
            "collection":"http://www.bubbagumpshrimp.com/rest/Employees/",
            "self":"12345",
            "reportsTo":"54321",
            "directReports":"12345/DirectReports"
        }
    }
}

感谢指导!

Answer 1

它“有效”，但它是多余的。有了 URI 后，为什么要保留不传达任何有关其语义或如何​​使用它们的裸 ID？我建议您试试这个:

{
    "employee":{
        "self":"http://www.bubbagumpshrimp.com/rest/Employees/12345",
        "fName":"Bubba",
        "lName":"Gump",
        "title":"Shrimp",
        "reportsTo":"http://www.bubbagumpshrimp.com/rest/Employees/54321",
        "directReports":"http://www.bubbagumpshrimp.com/rest/Employees/12345/directReports"
    }
}

(没有理由将“directReports”资源公开为“?reportsTo=12345”。通过其含义识别它总是比通过其实现更好。)

如果您可以控制您的 API 和/或媒体类型(并且您必须这样做是为了告诉您的客户在哪里期望 URI，因为 JSON 没有定义任何内容)，您甚至可以通过声明“reportsTo”和“directReports”值是相对于“self”的 URI:

{
    "employee":{
        "self":"http://www.bubbagumpshrimp.com/rest/Employees/12345",
        "fName":"Bubba",
        "lName":"Gump",
        "title":"Shrimp",
        "reportsTo":"54321",
        "directReports":"12345/directReports"
    }
}