Поскольку ряд товарищей спрашивает про сабж, попытаюсь поддерживать более менее актуальный список того что есть.
Общие моменты: все сервисы на данный момент на вход принимают параметры в виде form data (url для Get, тело запроса для Post), на выходе отдают JSON. Если результат с ошибками, возвращается HTTP код ошибки и JSON вида { field: "error_field", message: "error_message"}. Поле field, если оно есть, указывает на ошибку в конкретном входном параметре, либо содержит all, если ошибка к конкретному параметру не относится.
Аутентификация и сессия — общая с остальным сайтом, т.е. форма //Users/Login.aspx для логина, затем куки .RSDNAUTH и ASP.NET_SessionId.
Часть сервисов поддерживает ETag/If-None-Match и умеет возвращать 304, так что крайне желательно чтобы клиенты, отличные от браузеров, это использовали.
пустой респонс с 204 кодом, если все хорошо, либо информацию об ошибке
Оценка сообщения
Production
//rs/message/<messageId>/rate/<rateType>
POST
string rateType, — Тип оценки: rate, smile или agree
int messageID,
int? value — Значение оценки. Для типа rate: 1-3, для типа agree: -4 согласен, 0 не согласен
пустой респонс с 204 кодом, если все хорошо, либо информацию об ошибке
Удаление оценок
Production
//rs/message/<messageId>/rate
DELETE
int messageID,
пустой респонс с 204 кодом, если все хорошо, либо информацию об ошибке
Сообщение, включая его текст. В зависимости от значения formatted в качестве текста будет либо исходный код, либо готовый html для отображения
GET http://rsdn.ru/rs/message/5728645?formatted=true
{
"accountID":78670,
"createdOn":"\/Date(1407344805630)\/",
"id":5728645,"isClosed":null,
"name":null,
"rate":20,
"rateCount":10,
"agrees":0,
"disagrees":0,
"smiles":0,
"rowVersion":"0000A37F015BED19",
"subject":"Теперь вы все мои гости",
"authorNick":"Берсерк",
"text":"\u003ctable\u003e\u003ctr\u003e\u003ctd class=
\u0027m\u0027\u003e\u003cfont size=2\u003eВ
догонку к истории с Лабиринтом:\u003cbr
/\u003e\n\u003cbr /\u003e\n\u003cblockquote
class=\u0027q\u0027\u003e\u003cp\u003eРоссийские
туристы ..."
}
Получение сообщений топика
Alpha
//rs/topic/<topicId>/messages
GET
int topicId,
bool? formatted,
int? from,
int? len
Сообщения указанного топика, включая текст. В зависимости от значения formatted в качестве текста будет либо исходный код, либо готовый html для отображения
GET http://rsdn.ru/rs/topic/5727307/messages/?len=2&from=2
[
{
"accountId":99637,
"createdOn":"2014-08-05T23:03:52.2700000",
"id":5727307,
"isClosed":null,
"name":null,
"rate":5,
"rateCount":1,
"agrees":0,
"disagrees":0,
"smiles":0,
"rowVersion":"0000A37E017C1771",
"subject":"Некоторые недочеты",
"authorNick":"BrainSlug",
"text":"В принципе ничего серьезного. Но у меня при голосовании (rsdn.ru/poll/5136) под анонимом ...",
"gravatarHash":"35d4bb2787c66a855fdcf912d8f04ad6",
"forum":"rsdn",
"versions":[]
},
{
"accountId":99637,
"createdOn":"2014-08-06T21:13:51.8570000",
"id":5728657,
"isClosed":null,
"name":null,
"rate":0,
"rateCount":0,
"agrees":0,
"disagrees":0,
"smiles":0,
"rowVersion":"0000A37F015DE095",
"subject":"Re[2]: Некоторые недочеты",
"authorNick":"BrainSlug",
"text":"\r\nAVK\u003eНе воспроизвелось. У тебя воспроизводится?\r\nуже нет :)...",
"gravatarHash":"35d4bb2787c66a855fdcf912d8f04ad6",
"forum":"rsdn",
"versions":[]
}
]
Здравствуйте, AndrewVK, Вы писали:
AVK>Поскольку ряд товарищей спрашивает про сабж, попытаюсь поддерживать более менее актуальный список того что есть.
Спасибо! А можно сделать самое важное — получение списка тем в форуме, и собственно сообщений? Я тут на досуге пилю метро-клиент для винпланшетов, и пока приходится врукопашную html обрабатывать, что очень геморно — особенно в свете того, что вы постоянно меняете вёрстку...
Здравствуйте, Нахлобуч, Вы писали:
Н>Не хочу показаться занудой, но это не совсем REST. Гораздо ближе к RPC-подобному API с JSON на выхлопе.
Ну давай глянем вики:
Client–server
Stateless
Cacheable
Layered system
Code on demand (optional)
Uniform interface
Identification of resources
Manipulation of resources through these representations
Self-descriptive messages
Что из этого, кроме code on demand, принципиально не подходит?
... << RSDN@Home 1.2.0 alpha 5 rev. 100 on Windows 8 6.2.9200.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Здравствуйте, Нахлобуч, Вы писали:
Н>>Не хочу показаться занудой, но это не совсем REST. Гораздо ближе к RPC-подобному API с JSON на выхлопе.
AVK>Ну давай глянем вики:
Мы академиев не кончали, но есть мнение, что ресурса "/f/ratemessage/{id}" (и подобных "/f/gettopics") не существует. А параметр "bool set" говорит о RPC-направленности. Как мне кажется, более тру было бы что-то типа "/forum/{name}/messages/{id}/rates" с операциями GET и POST (rate = 1|2|3|smile|upvote|downvote), а так же DELETE для "../rates/{rate}". С остальными "ресурсами" -- аналогично.
"Пустой респонс с 200 кодом" -- это 204. Всегда плеваться пятисотой ошибкой тоже не шибко канонично.
Ну и HATEOAS, но это совсем уже высший пилотаж.
HgLab: Mercurial Server and Repository Management for Windows
Здравствуйте, Нахлобуч, Вы писали:
Н>Мы академиев не кончали, но есть мнение, что ресурса "/f/ratemessage/{id}" (и подобных "/f/gettopics") не существует.
Почему ты так решил? Они вполне существуют, просто не все реализовано . Смутило get? Это просто для гарантии отсутствия конфликта с урлами страничек. Впрочем, уже переделано на /rs/forum/<forumname>/topics. <forumname>/topics — идентификатор ресурса.
Н> А параметр "bool set" говорит о RPC-направленности
Ничего подобного он не говорит, это тело POST запроса.
Н>. Как мне кажется, более тру было бы что-то типа "/forum/{name}/messages/{id}/rates" с операциями GET и POST (rate = 1|2|3|smile|upvote|downvote), а так же DELETE для "../rates/{rate}". С остальными "ресурсами" -- аналогично.
Это несложно переделать. Насчет DELETE так наверняка, заодно set выкинется.
Н>"Пустой респонс с 200 кодом" -- это 204.
В смысле?
Н> Всегда плеваться пятисотой ошибкой тоже не шибко канонично.
А оно там не всегда, я просто не описал. Бывает, как минимум, еще 400, 403 и 404.
Н>Ну и HATEOAS, но это совсем уже высший пилотаж.
Это в данном случае совсем без надобности.
... << RSDN@Home 1.2.0 alpha 5 rev. 100 on Windows 8 6.2.9200.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Добавил получение ответов
Спасибо! Вопросы (смотрю на вывод http://rsdn.ru/rs/topic/5728024/replies ):
1. Нужен ParentId, чтобы можно было построить дерево.
2. Что такое "name" (который null) и "rowVersion"?
3. дата "createdOn" я так понимаю в тиках?
Здравствуйте, koandrew, Вы писали:
K>1. Нужен ParentId, чтобы можно было построить дерево.
Упустил момент, поправлю
K>2. Что такое "name" (который null) и "rowVersion"?
У некоторых сообщений есть уникальное имя. Потом на них можно сослаться [#имя_сообщения].
RowVersion это равномерно возрастающее число, обновляющееся при каждом изменении сообщения.
K>3. дата "createdOn" я так понимаю в тиках?
Здравствуйте, AndrewVK, Вы писали:
Н>>Мы академиев не кончали, но есть мнение, что ресурса "/f/ratemessage/{id}" (и подобных "/f/gettopics") не существует. AVK>Почему ты так решил?
Потому, что наличие глагола в имени ресурса делает его не совсем ресурсом.
Н>> А параметр "bool set" говорит о RPC-направленности AVK>Ничего подобного он не говорит, это тело POST запроса.
Да, это тело RPC-стайл POST-запроса. Если бы происходила манипуляция ресурсами, то было бы ровно так, как я описывал:
"/forum/{name}/messages/{id}/rates" с операциями GET и POST (rate = 1|2|3|smile|upvote|downvote), а так же DELETE для "../rates/{rate}"
Н>>"Пустой респонс с 200 кодом" -- это 204. AVK>В смысле?
В смысле, по заветам HTTP каноничнее было бы в ответ на успешный POST-запрос возвращать не пустой ответ с HTTP 200, а пустой ответ с HTTP 204.
AVK>Это в данном случае совсем без надобности.
См. свой пассаж о "переделано". Если бы в результате переделок сервер научился бы выплевывать HTTP 301 для перенаправления со старых на новые URL'ы и эти URL'ы не формировались бы клиентом, а получались непосредственно из ответа, то жизнь клиентских приложений была бы тёплой и сухой.
И раз уж мы заговорили о REST и Stateless'ности -- может быть, подумать насчет какого-то альтернативного способа аутентификации и авторизации?
HgLab: Mercurial Server and Repository Management for Windows
Здравствуйте, Нахлобуч, Вы писали:
Н>Потому, что наличие глагола в имени ресурса делает его не совсем ресурсом.
Ну я так и подумал.
Н>См. свой пассаж о "переделано". Если бы в результате переделок сервер научился бы выплевывать HTTP 301 для перенаправления со старых на новые URL'ы и эти URL'ы не формировались бы клиентом, а получались непосредственно из ответа, то жизнь клиентских приложений была бы тёплой и сухой.
Пока никаких клиентских приложений для этих сервисов нет.
Н>И раз уж мы заговорили о REST и Stateless'ности -- может быть, подумать насчет какого-то альтернативного способа аутентификации и авторизации?
Может быть. Какого?
... << RSDN@Home 1.2.0 alpha 5 rev. 100 on Windows 8 6.2.9200.0>>
Здравствуйте, AndrewVK, Вы писали:
Н>>И раз уж мы заговорили о REST и Stateless'ности -- может быть, подумать насчет какого-то альтернативного способа аутентификации и авторизации? AVK>Может быть. Какого?
Сам напрашивается Basic (и HTTPS, разумеется). Или что-то типа такого.
HgLab: Mercurial Server and Repository Management for Windows
Здравствуйте, Нахлобуч, Вы писали:
Н>Сам напрашивается Basic (и HTTPS, разумеется).
Basic предполагает хранение на клиенте пароля, что не здорово.
Н> Или что-то типа такого.
Что то такое в планах, только пока без конкретно OAuth2. В первой итерации, скорее всего, будет просто метод Login, возвращающий те же самые данные, что и форма. Аналог Login.aspx, только без вьюстейтов.
... << RSDN@Home 1.2.0 alpha 5 rev. 100 on Windows 8 6.2.9200.0>>
. Смутило get? Это просто для гарантии отсутствия конфликта с урлами страничек. Впрочем, уже переделано на /rs/forum/<forumname>/topics. <forumname>/topics — идентификатор ресурса.
