REST JSON规范

Question

我是 SOAP 和 REST 编程的新手。

• 在 SOAP 中，正在交换的实体的结构和字段 在 WSDL 。

中总是很好地和明确地记录

• 我认为在 REST 中不会发生同样的情况。

REST API 的开发人员应该怎么做 记录 JSON 对象的结构和所有字段，表示正在交换的实体？

Answer 1

REST和SOAP无法直接进行比较，因为它们是非常不同的东西。如果需要，可以通过SOAP实现REST，但不能相反。我建议阅读this answer。

在RESTful API中，您应该正确记录媒体类型并让交互由底层协议驱动，但不要在大多数自称为REST的HTTP API中查找。他们使用这个术语作为流行语，并经常做相反的事情，记录协议而不是媒体类型。

例如，如果您有一个User资源，那么您应该以类似JSON或XML的格式（如application/vnd.mycompany.user.v1+json）为其提供适当的媒体类型，并且您的文档应描述此JSON文档的内容看起来像客户端知道会发生什么。这并不像WSDL那样严格。事实上，它可以是一个人类可读的文档，就像你为记录类API或类似的东西所做的那样。

客户端可以通过Accept标题说出他准备接受的媒体类型。例如，如果客户端想要JSON中的v1表示，他可以使用类似的东西：

GET /users/xyz
Accept: application/vnd.mycompany.user.v1+json

如果他想要XML中的v2表示，他可以使用类似的东西：

GET /users/xyz
Accept: application/vnd.mycompany.user.v2+xml

如果他只是想要JSON并让服务器决定做什么，他可以使用通用媒体类型，并通过检查Content-Type响应标头找出服务器向他投掷的内容。

GET /users/xyz
Accept: application/json

但是，请记住，您发现的大多数所谓的REST API都不会使用这样的自定义媒体类型。相反，他们在任何地方都使用相同的通用媒体类型，例如application/json和application/xml。这意味着客户端必须通过URI语义和关系来识别资源，而这根本不是REST。我并不是说它错了，它很简单并适用于许多问题，但它不是REST而且它并没有解决REST真正打算的同类问题解决。

Answer 2

REST没有建立或建议您构建数据的方法。它的唯一目的是让任何人都可以轻松找出API支持的方法和实体。您甚至不需要在REST API中输出JSON。