REST JSON 规范
REST JSON specification
我是 SOAP 和 REST 编程的新手。
在SOAP中被交换的实体的结构和字段
在 WSDL.
我认为在 REST 中不会发生同样的情况。
REST API 的开发者应该如何
记录 JSON 对象的结构和所有字段，代表正在交换的实体？
REST 不会为您建立或推荐一种构建数据的方法。这只是为了让任何人都能轻松地弄清楚您的 API 支持哪些方法和实体。您甚至不一定需要在 REST API.
中输出 JSON
不能直接比较 REST 和 SOAP，因为它们是非常不同的东西。如果需要，您可以通过 SOAP 实现 REST，但反之则不行。我推荐阅读 this answer.
在 RESTful API 中，您应该正确记录您的 media-types 并让交互由底层协议驱动，但不要在大多数情况下寻找它自称为 REST 的 HTTP APIs。他们将该术语用作流行语，并且经常做相反的事情，记录协议而不是 media-types。
例如，如果你有一个用户资源，你应该有一个适当的 media-type 格式如 JSON 或 XML 看起来像 application/vnd.mycompany.user.v1+json，并且您的文档应该描述此 JSON 文档的外观，以便客户知道会发生什么。这不必像 WSDL 那样严格。事实上，它可以是人类可读的文档，就像您为记录 class API 或类似内容所做的那样。
客户可以用Acceptheader说出media-types他准备接受什么。例如，如果客户想要 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 并让服务器决定要做什么，他可以使用通用 media-type 并通过检查 Content-Type 响应 header.
GET /users/xyz
Accept: application/json
但是，请记住，您会发现大多数所谓的 REST API 不会像这样使用自定义 media-types。相反，他们到处都使用与 application/json 和 application/xml 相同的通用 media-types。这意味着客户端必须通过 URI 语义和关系来识别资源，而这根本不是 REST。我并不是说它是错误的，它很简单并且适用于许多问题，但它不是 REST，也没有解决 REST 真正打算解决的同类问题。
我是 SOAP 和 REST 编程的新手。
在SOAP中被交换的实体的结构和字段 在 WSDL.
中总是有清晰明确的记录
我认为在 REST 中不会发生同样的情况。
REST API 的开发者应该如何 记录 JSON 对象的结构和所有字段，代表正在交换的实体？
REST 不会为您建立或推荐一种构建数据的方法。这只是为了让任何人都能轻松地弄清楚您的 API 支持哪些方法和实体。您甚至不一定需要在 REST API.
中输出 JSON不能直接比较 REST 和 SOAP，因为它们是非常不同的东西。如果需要，您可以通过 SOAP 实现 REST，但反之则不行。我推荐阅读 this answer.
在 RESTful API 中，您应该正确记录您的 media-types 并让交互由底层协议驱动，但不要在大多数情况下寻找它自称为 REST 的 HTTP APIs。他们将该术语用作流行语，并且经常做相反的事情，记录协议而不是 media-types。
例如，如果你有一个用户资源，你应该有一个适当的 media-type 格式如 JSON 或 XML 看起来像 application/vnd.mycompany.user.v1+json，并且您的文档应该描述此 JSON 文档的外观，以便客户知道会发生什么。这不必像 WSDL 那样严格。事实上，它可以是人类可读的文档，就像您为记录 class API 或类似内容所做的那样。
客户可以用Acceptheader说出media-types他准备接受什么。例如，如果客户想要 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 并让服务器决定要做什么，他可以使用通用 media-type 并通过检查 Content-Type 响应 header.
GET /users/xyz
Accept: application/json
但是，请记住，您会发现大多数所谓的 REST API 不会像这样使用自定义 media-types。相反，他们到处都使用与 application/json 和 application/xml 相同的通用 media-types。这意味着客户端必须通过 URI 语义和关系来识别资源，而这根本不是 REST。我并不是说它是错误的，它很简单并且适用于许多问题，但它不是 REST，也没有解决 REST 真正打算解决的同类问题。