REST JSON спецификация

Question

Я новичок как в SOAP и ОТДЫХ программирование.

• В SOAP структура и поля субъектов обмениваемых всегда хорошо и однозначно описаны в WSDL.

• Я думаю, что такого же не происходит в ОТДЫХ.

Как разработчик REST API должен документ структура и всех полей JSON объектов, представляющих объекты, которыми обмениваются?

Answer 1

ОТДЫХ И МЫТЬ нельзя сравнивать напрямую, так как они очень разные вещи. Вы можете реализовать REST поверх SOAP, если хотите, но не наоборот. Рекомендую прочитать this answer.

В API-интерфейсах RESTful вы должны правильно документировать свои медиа-типы и позволить взаимодействию управлять базовым протоколом, но не ищите его в большинстве HTTP-API, которые называют себя REST. Они используют этот термин в качестве модного слова и часто делают противоположное этому, документируя протокол вместо медиа-типов.

Например, если у вас есть ресурс пользователя, у вас должен быть подходящий тип медиафайла для него в формате JSON или XML, который выглядит как application/vnd.mycompany.user.v1+json, и ваша документация должна описывать, как выглядит этот документ JSON. клиент знает, чего ожидать. Это не должно быть столь же строгим, как WSDL. На самом деле, это может быть удобная для чтения документация, например, для документирования API класса или чего-то подобного.

Клиент может сказать, какие медиа-типы он готов принять с заголовком Accept. Например, если клиент хочет представление v1 в формате JSON, он может использовать что-то вроде:

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

Если он хочет, чтобы представление v2 в XML, он может использовать что-то вроде:

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

ОТДЫХ не устанавливает и не рекомендует вам структурировать данные. Он предназначен только для того, чтобы каждый мог выяснить, какие методы и сущности поддерживает ваш API. Вы даже не обязательно должны выводить JSON в свой REST API.