Как правильно спроектировать протокол обмена данными между клиентом и веб-сервисом?

Question

[bazzilic]

Привет!

Я создаю некоторый веб-сервис с публичным API, доступным по HTTP. Так как API предполагается публичным, хочется учесть все подводные камни заранее — иначе придётся делать новую версию протокола и поддерживать обе — ужас :)

Общение между клиентом и сервером работает в лучших традициях HTTP: запрос-ответ. Все параметры запроса передаются в соответствии с правилами HTTP — через адресную строку для GET-запросов и через multipart/form-data для POST. Для разных задач — разные URL, например, запрос на логин отправляется по адресу http://example.com/login, а на регистрацию — по адресу http://example.com/register)

Однако, не очень понятно, как оформить передачу данных обратно клиенту. На данный момент, информацию о результате запроса я кодирую HTTP статусом (200, 403, 404, 500, etc.), а если нужно что-то еще, то я просто передаю клиенту сплошным текстом значения в заданном порядке, разделённые символом-разделителем (например, 17:150:колбаса) в теле ответа.

Я подумал было, что имеет смысл использовать для этого XML, ибо сейчас все так делают — наверно неспроста. Но, поизучав эту тему, понял, что при таком подходе принято и параметры запроса на сервер передавать в виде XML.

Как быть? Использовать простую строку параметров с разделителями или переходить на XML? Можно ли при этом отправлять данные серверу всё-таки в виде параметров запроса?

Интересуют ответы с точки зрения того, что принято или не принято и насколько это плохо — отходить от принятого. Физически-то как угодно можно сделать.

Answer 1

[vanxant]

Во-первых, забудьте про XML, его придумали бюрократы. Вот пусть они его и используют в своих банках и налоговых. Для парсинга и кодирования JSON достаточно пары функций по 10 строк каждая. Для парсинга XML, даже если в нем пару значений, нужно подгружать монструозные библиотеки.

Во-вторых, раз уж вы делаете веб-приложение, используйте возможности протокола HTTP. Это значит идеология REST, а не RPC. То есть вместо каких-то там «процедур» или «функций», вы пляшете от объектов и стандартных действий.
Например, у вас есть объект с идентификатором obj_id. Для любого доступа к нему используется URL вида

example.com/path/to/obj_id

Далее по этому URL-у возможны 4 действия (http verb):
GET example.com/path/to/obj_id — получить данные объекта
PUT example.com/path/to/obj_id — изменить объект
DELETE example.com/path/to/obj_id — удалить объект
POST example.com/path/to/ — создать новый объект в папке /path/to
GET example.com/path/to/ — получить все объекты в папке /path/to

В зависимости от результата операции, вы должны возвращать правильные коды ошибок (200 OK, 404 Not Found, 403 Forbidden и т.п.).

Параметры более сложных запросов идут как get-параметры, ну например
GET example.com/path/to/?search=blabla
— искать объекты
Или можно часть параметров перенести в урл:
GET example.com/my/report/01.01.2011-31.12.2011/

Comments

[vanxant]

Да, еще можно формат вывода определять через «расширение файла».
Ну то есть
GET example.com/path/to/obj_id.json — JSON
GET example.com/path/to/obj_id.xml — XML, если он вдруг потребуется
GET example.com/path/to/obj_id.html — «человеко-читаемый» вид в HTML

[Алексей Сундуков]

Лучше все же через content-type. Ибо через «расширение файла» получается три разных ресурса. Хотя по сути он один. Уже если пропагандируем REST, то будем последовательны и следовать ему будем до конца.

[akral]

HTTP 1.1, заголовок Accept.

[vanxant]

Content-type это красиво, но уж слишком много танцев с бубном для клиентов. В сервисах яндекса, например, используется таки псевдо-расширение.

Answer 2

[DevMan]

REST + XML/JSON

Answer 3

[Moxa]

добавьте параметр format к запросу и, в зависимости от его значения, отдавайте json/xml/csv…

Comments

[bazzilic]

Да, хорошая идея, кстати, спасибо! :)

[Mikhail Osher]

И на крайний случай параметр api_version (назовите, как посчитаете нужным), как сделали VK.

[akral]

HTTP 1.1, заголовок Accept.

Answer 4

[AlexNomad]

XML все-таки тормознутее.
Я в похожей ситуации выбрал JSON из-за его скорости.
Нужно оценить везде ли вы сможете применять JSON.
Если нет, то иных вариантов кроме XML нет.

Comments

[bazzilic]

Тормознутее в плане чего? Парсинг? Или объём передаваемых данных?
В любом случае, у меня речь идёт о передаче 2-3 числовых значений пару раз, тут скорость не сильно играет роль, я думаю.

[DevMan]

Для меня JSON предпочтительнее по следующим причинам:
— меньший объем данных
— данные легче визуализировать (ИМХО)

да и парсить «легче».

Answer 5

[charon]

сам сталкивался с такой задачей — она не так уж и проста. С большинством советов выше я согласен.
1) Используйте json-encode — очень распространённое и проверенное решение. Значительно проще xml.
2) Разделение типов запросов на HTTP-методы GET, POST, PUT, DELETE лучше не делать, хотя это и правильно. Ограничьтесь GET и POST. Это связано с тем, что многие клиенты не смогут использовать тот же DELETE — ну вот хотя бы флэш.
3) Сразу предусмотрите версии вашего API. То есть в запросе обязательно должен быть параметр типа v=1. В будущем это вам очень пригодится.

Comments

[bazzilic]

Спасибо! Тоже решил не связывать с PUT и DELETE.

[Владимир Чернышев]

Насчёт PUT и DELETE: общепринятая практика эмулировать их в браузере отправкой параметра _method в POST- запросе

Answer 6

[Fortop]

Я бы предложил не изобретать велосипед, а воспользоваться RPC/SOAP

Comments

[Fortop]

Но если сильно хочется то, к примеру, в ZF есть REST server

[bazzilic]

Что такое ZF?

[DevMan]

Zend Framework

[bazzilic]

Я использую python + tornado в качестве сервера.

[DevMan]

Разве на tornado сложно реализовать RESTful?

[Fortop]

SOAP и RPC есть и в Питоне — это стандарт

[vanxant]

SOAP — монструозный, глюкавый, несовместимый, никому не нужный и абсолютно бесполезный ужас. Забудьте как страшный сон.

[Fortop]

Кто и с чем несовместимый?
У вас вообще есть опыт работы с ним? Или просто пальцем потыкали?

Answer 7

[MikhailEdoshin]

Часто выбор формата делают либо через «расширение файла» (domain.com/method.xml vs method.json), либо через HTTP-заголовок Accept.

Answer 8

[karenishe]

Исходя из моего опыта, порядок действий должен быть такой:
1. Попробовать разные API как «юзер» (facebook, twitter, vkontakte, soundcloud, youtube);
2. Понять, что нравится, а что нет (опять же, как «юзеру»);
3. Делать свой API исходя из первых двух пунктов.

На мой взгляд, необходимо придерживаться идеологии REST (с возможностью обходиться и без нее), а по форматам допускать как xml, так и json.

Answer 9

[strelok_aka_vc]

Я подумал было, что имеет смысл использовать для этого XML, ибо сейчас все так делают — наверно неспроста. Но, поизучав эту тему, понял, что при таком подходе принято и параметры запроса на сервер передавать в виде XML.

Не совсем понял как Вы себе представляете GET запрос на сервер с XML данными.
Ответ от сервера в виде XML — общепринятая практика. Используется в платежных системах повсеместно.

Comments

[bazzilic]

Ну, в таком случае, конечно, придется делать POST-запрос.

[gouranga]

Если следовать концепции REST, то

HTTP Method	CRUD Action	Description
POST	CREATE	Create a new resource
GET	RETRIEVE	Retrieve a representation of a resource
PUT	UPDATE	Update a resource
DELETE	DELETE	Delete a resource

И да, переходите на xml. Можно добавить еще json (вдруг кому-то он будет удобнее), разница будет только в сериализации. Получите что-то вроде api.example.com/1.0/xml/methodName.

[1010101001000100110100111]

Например в Яндексе Как задать XML-запрос методом GET?

Когда XML-запрос задается методом GET, каждый элемент XML-запроса преобразуется в соответствующий CGI-параметр. Элемент groupings не используется, вместо него надо перечислить все groupby, содержимое которых кодировать надо чуть-чуть иначе: разделителем параметров служит символ точки «.», а знак равенства «=» заменяется на его escape-последовательность «%3D».