Как аноним и зарегистрированный я хочу видеть список разделов (аналогичный списку http://www.linux.org.ru/forum/), чтобы отобразить его в стороннем приложении.

Каждый элемент списка должен содержать структуру:

{
  id: уникальный идентификатор раздела
  alias: краткое обозначение раздела (general)
  name: название раздела (общий форум для технических вопросов, не подходящих в другие группы)
  count_all: сколько всего сообщений в разделе
  count_today: сколько сообщений было добавлено сегодня
}

Как аноним и зарегистрированный я хочу видеть список тем(топиков) в заданном форуме, чтобы отобразить его в стороннем приложении.

Список тем должен быть аналогичен этому: www.linux.org.ru/forum/general/

Список должен иметь возможность сортировки по:

• названию
  
• дате создания топика
  
• дате последнего комментария в топике
  

Список должен иметь возможность задания диапазонов, чтобы можно было получать топики порциями со смещением от начала.

каждый элемент списка должен содержать стуктуру:

{
  id: идентификационный номер топика
  isSticky: признак прекреплённой темы
  isCompleted: признак решённого топика
  author: автор топика
  title: заголовок топика
  count_total: всего ответов
  count_daily: ответов за день
  count_hourly: ответов за час
  tags[]: {  теги топика
     name: название тега
  }
}

Как аноним и зарегистрированный я хочу видеть список тем(топиков) в заданном форуме, чтобы отобразить его в стороннем приложении.

с прикреплёнными надо что-то делать. Наверное, будет лучше, если можно будет задавать отдельный запрос на получение только прикреплённых тем. а обычный запрос не должен содержать прикреплённые. Это надо, чтобы прекреплённые можно было отображать специальным образом в сторонних приложениях (в начале списка или вообще в отдельном списке).

Пожалуй, к этой пользовательской истории надо добавить ещё одно требование:

«Список должен иметь возможность выборки только прикреплённых топиков или всех, кроме прикреплённых.»

Тогда поле «isSticky» теряет смысл.

1. Как писатель своих скриптов я хочу иметь возможность вытаскивать посты и комментарии по id, чтобы... ну эта, писать скрипты. 2. http://api.linux.org.ru/post/12345, ответ по желанию клиента html, xml или json. 3. По требованию.

Ответ в HTML не нужен, это бред.

Как писатель своих скриптов

Немного не так. надо относительно ролей, использующихся в самом приложении:

1) аноним
2) зарегистрированный
2.1) модератор
2.2) корректор

я хочу иметь возможность вытаскивать посты и комментарии по id,

Это немного обобщающее требование. Оно запросто может быть разбито на несколько историй. А если может быть разбито - значит, оно должно быть разбито. Постановка задач должна быть максимально простой, «разжёванной» и атомарной по возможности.

Если бы LOR это еще и отдавал в POST-ответе.

А зачем в POST?

Списки - это в чистом виде GET по идее.

PUT - добавили новый топик
GET (list) получили список топиков (в том числе и новодобавленный топик).
PUT/POST - изменили топик
DELETE - удалили

P.S. мы сейчас про RESTfull говорим?

Да, в принципе, не нужен.

tags[]: {  
     name: название тега
  }

Что за бред, объект с одним свойством? Чем массив то не понравился?

А ещё там и camelCase и underscore намешаны, derlaff даже черту воткнул.

Как аноним и зарегистрированный я хочу видеть список сообщений (аналогичный просмотру этой темы), чтобы отобразить его в стороннем приложении.

Список должен принимать параметры:

• Страницу, которую я хочу получить ИЛИ одиночный id сообщения/темы
• ID последнего поста, который у меня уже есть, если режим страницы
• Количество сообщений на страницу, если режим страницы
• Показ/скрытие игнорируемых сообщений, если режим страницы
• Показ/скрытие удаленных сообщений, если режим страницы

Если сообщение изменилось, но я передал параметр, указывающий, что у меня это сообщение уже есть, я всё равно хочу видеть его в списке

Каждый элемент списка должен содержать структуру:

{
  id: уникальный индетификатор сообщения
  istopic: true, если это топик
  title: заголовок сообщения
  body: содержание сообщения. желательно в каком-нибудь markdown. На худой случай в LORCODE, но его очень печально парсить
  poster: ник постера
  poster_banned: зачеркивать ли ник
  stars: количество звезд постера
  gray: количество серых звезд постера
  date: дата и время в unix timestamp
  tags[]: {  если топик, то теги
     name: название тега
  }
  flags: первый бит в 1, если сообщение можно удалить, второй, если можно редактировать, третий, если сообщение - тема и она отмечена решенной
  del_reason: причина удаления
  del_author: автор удаления
  last_edit_date: UNIX Timestamp последнего редактирования
  last_edit_author: ник последнего редактора
  edit_number: количество редактирований
  score: только для модераторов
  maxscore: только для модераторов
  ua: только для модераторов
}

Как аноним и зарегистрированный я хочу получать URL аватарки для отображения её в стороннем приложении

Входные параметры:

• Ник или ID пользователя

Список состоит из одного элемента со структурой:

{
  url: URL аватарки без http:// или https://
  isgravatar: используется ли gravatar или внутреннее хранилище ЛОРа
}

Что за бред, объект с одним свойством? Чем массив то не понравился?

Принято. Будет простой массив.

А ещё там и camelCase и underscore намешаны, derlaff даже черту воткнул.

Да, верно, намешал я всё. будет camelCase.

Спасибо за критику.

С аватарками получается как бы три состояния:
1) нет аватарки
2) граватар
3) хранится на ЛОРе

Может, какой enum продумать?

1) Как (регистрант|аноним) я хочу видеть список ответов на сообщение с указанным id для улучшения функционала своего юзерскрипта.

2) Список ответов должен включать в себя всю информацию, которая сейчас присутствует на странице. Желательно включать флаг, сигнализирующий о том, есть ли у данного ответа ещё ответы (возвращать всё дерево ответов не надо). Нужно учитывать игнорируемых пользователей.

3)

GET /children?id=12345

[
  {
    id: 12346,
    author: "Legioner",
    authorStars: [1, 1, 1, 1, 1], // 1 - green, 0 - gray
    title: "asd",
    text: "<p>Hello, <b>world</b>!\n\ntest",
    hasReplies: true
  },
  {
    id: 12347,
    author: "Legioner",
    authorStars: [1, 1, 1, 1, 1],
    title: "asd2",
    text: "<p>Hello, <b>world</b>!\n\ntest",
    hasReplies: false
  }
]
    

Даже 4. Можно так же, как и flags

Первый бит - 1, если есть аватарка.

Второй бит - 0, если на ЛОРе, 1 - если граватарка. Игнорируется, если первый - нуль

0: нет
2: граватарка-затычка
3: граватарка
5: ЛОР-аватарка

Или обычный енам (0, 1, 2, 3)

Для простоты можно сделать два поля, isgravatar и isempty

Страницу, которую я хочу получить ИЛИ одиночный id сообщения/темы
Количество сообщений на страницу, если режим страницы

номер страницы и количество сообщений на страницу - это понятно:
&page=xx&itemsPerPage=30

а тут хочу уточнить:

ИЛИ одиночный id сообщения/темы
ID последнего поста, который у меня уже есть, если режим страницы

То есть, передаём ID последнего сообщения, которое есть у нас, а в ответ должны получить список более новых сообщений, которые случились после этого ID. Так?

Если сообщение изменилось, но я передал параметр, указывающий, что у меня это сообщение уже есть, я всё равно хочу видеть его в списке

Может, вместо lastID лучше передавать некий lastModifiedTimestamp, чтобы получить список не только более новых сообщений, но и ранее изменённые сообщения в этом же списке.

Показ/скрытие удаленных сообщений, если режим страницы

Почему бы и нет.
api.l.o.r можно будет закрыть всем поисковым роботам и вполне с комфортом через GET можно будет получать удалённые.

Каждый элемент списка должен содержать структуру:

Забыл спросить: inReplyTo надо?

Как зарегистрированный пользователь я хочу видеть количество и список уведомлений, разделенные по категориям (ответы, касты, темы).

Надо. Желательно и id, и title

Желательно и id, и title

Ну... хотелось бы часть логики перенести на сторону клиента. :)

То есть, передаём ID последнего сообщения, которое есть у нас, а в ответ должны получить список более новых сообщений, которые случились после этого ID. Так?

Да.

Может, вместо lastID лучше передавать некий lastModifiedTimestamp, чтобы получить список не только более новых сообщений, но и ранее изменённые сообщения в этом же списке.

Можно. Я знаю, что в базе ЛОРа уже есть аналогичное поле, его можно использовать, когда пользователь зарегистрирован и timestamp не передан.

Ну... хотелось бы часть логики перенести на сторону клиента. :)

А, ну тогда ID хватит.

Еще фичреквест: дополнительный фильтр «fields», который позволит получать только нужные поля запроса.

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

GET api.jsp?filter=title,date,poster&a=getpost&id=123456

Как зарегистрированный пользователь я хочу видеть количество и список уведомлений, разделенные по категориям (ответы, касты, темы).

При этом желательно указывать время последнего получения списка
lastSeenTimestamp=xxxxxx

чтобы каждый раз не получать весь список заново.

Каждый элемент в списке должен иметь поля:

...

И возможность сбросить счетчик тоже нужна. Т.е. если юзер в клиенте просмотрел уведомления — в браузере они не должны быть помечены как новые.

накидал пользовательские истории:

https://github.com/slavaz/lorsource/issues?milestone=3&sort=created&s...

Этого будет достаточно для R/O доступа?
Какие есть пожелания/замечания/критика по описанным историям?

P.S. Возможность записи через API пока что отложим: пусть этот процесс будет поэтапным.

Накидал документашку для будущего кода с примерами:

https://github.com/slavaz/lorsource/wiki/REST-API

У кого есть замечания, предложения, критика - высказывайте, плиз. Чем больше обговорим, тем больше шансов получить то, что вам надо, а не то что «они там понаписали, а мне тут извращайся».

hizel:
Ильдар, как обстоят дела со SpringSecurity? Нужна помощь? Думаю начать REST-API после твоего бранча, но не знаю как поступить: то ли отпочковаться от твоего бранча (если он надолго будет не в мастере), то ли помочь тебе, если там есть какие-то нерешённые вопросы и быстрее его влить в мастер.

да надо потестировать как оно, проверить не светится ли приватная информация куда не надо. просмотреть глазками. я в эти выходные свободен и собираюсь за пулл рекуестить в конце концов. :]

В каком формате будет отдаваться содержание постов?

в таком, в каком оно хранится в базе. Сейчас это LORcode

я в эти выходные свободен и собираюсь за пулл рекуестить в конце концов. :]

Я, к сожалению, не свободен - буду в командировке на тренинге с казённым ноутбуком. Постараюсь потом, попозже поревьювать код.

Как модератор я хочу модерировать, чтобы модерировать.

Хочу всю полноту власти на ЛОРе в виде андроидной аппликухи.

Никаких условий :).

<input type=«button» value=«Сделать мне очень хорошо»>
<input type=«button» value=«Совершить после обеда подвиг»>
<input type=«button» value=«Забанить навсегда всех неадекватов и их будущих виртуалов»>


Я тебе уже целых три кнопки для андроид-интерфеса модерилки придумал, остался сущий пустяк: надо реализовать :)

Ох как здорово. Готов за эффективную реализацию отдать три звезды.

для модератора три звезды — мелочь и пустяк

Хорошо, забирай все 8, но сделай :).

И мои 9!

ты не можешь выдать мне или кому нибудь ни одной звезды. следовательно шквор и звезды не могут быть денежными единицами.

хм... хотя есть вариант, отдать полностью аккаунт ^_^

ты не можешь выдать мне или кому нибудь ни одной звезды.

Я знаю того, кто может :).

я знаю двух таких :P от этого моему шкворцу ни сухо ни холодно

При score >= 500 уже пофигу.

ОК, я знаю троих. И чё :)?

кароче, шквор не нужен, давай два ведра гиннеса и приложение твое :}

Приезжай!