Очередной опус. Встречаем! 

2. Доступ к информации об участнике форума

а) доступ по UserID

Аргумент -> data
Значение -> user

Аргумент -> id
Значение -> номер идентификатора участника, например для главного админа он равен 2

Возвращает строку со всей доступной информацией об участнике форума, кроме идентификационного номера.

Пример:
Запрос:

http://forum.mybb.ru/api.php?data=user&id=2

Ответ:

{"ключ":"значение","ключ":"значение" и т.д.}

Используемые ключи:
sex - пол. Если не установлен - 0, женский - 1, мужской 2
age - возраст, если не установлен, то 0
name - имя, указанное в профиле, если не указано - пустая текстовая строка
posts - число постов данного юзера
style - стиль установленый в профиле
status - статус участника
avatar - относительный путь к аватару строкой, т.е. "/img/avatars/********.jpg"
invited - кол-во участников, зареганных по приглашению юзера
groupId - идентификационный номер группы
location - откуда (из профиля инфа), если нет - пустая текст. строка
lastPost - дата последнего сообщения в секундах от начала эпохи UNIX
lastVisit - дата последнего визита в секундах от начала эпохи UNIX
totalTime - время проведённое онлайн на форуме в секундах
userLogin - логин
birthDate - дата рождения в секундах от начала эпохи UNIX
groupTitle - название группы
registered - дата регистрации на форуме (для гл. админа момент создания форума) в секундах от начала эпохи UNIX
inviteCode - код инвайта
respectPlus - кол-во плюсов полученных участником, если значение положит. то без плюса, но если отриц. - то минус указать
respectMinus - кол-во минусов полученных участником, если значение положит. то без плюса, но если отриц. - то минус указать
positivePlus - кол-во плюсов данных участником, если значение положит. то без плюса, но если отриц. - то минус указать
positiveMinus - кол-во минусов полученных участником, если значение положит. то без плюса, но если отриц. - то минус указать

Получение только нужных данных
Это возможно при использовании доп. аргументов со значением 1.

Примеры:
Запрос:

http://forum.mybb.ru/api.php?data=user&id=5&login=1

Ответ:

{"login":"Мракобес"}

Запрос:

http://forum.mybb.ru/api.php?data=user&id=17&login=1&style=1

Ответ:

{"login":"Пацифист","style":"Cobalt"}

----------------------

б) доступ по UserLogin

Аргумент -> data
Значение -> user

Аргумент -> login
Значение -> логин участника

Возвращает строку со всей доступной информацией об участнике форума, кроме логина.

Пример:
Запрос:

http://forum.mybb.ru/api.php?data=user&login=Admin

Ответ:

{"ключ":"значение","ключ":"значение" и т.д.}

Используемые ключи:
id - номер идентификатора участника
sex - пол. Если не установлен - 0, женский - 1, мужской 2
age - возраст, если не установлен, то 0
name - имя, указанное в профиле, если не указано - пустая текстовая строка
posts - число постов данного юзера
style - стиль установленый в профиле
status - статус участника
avatar - относительный путь к аватару строкой, т.е. "/img/avatars/********.jpg"
invited - кол-во участников, зареганных по приглашению юзера
groupId - идентификационный номер группы
location - откуда (из профиля инфа), если нет - пустая текст. строка
lastPost - дата последнего сообщения в секундах от начала эпохи UNIX
lastVisit - дата последнего визита в секундах от начала эпохи UNIX
totalTime - время проведённое онлайн на форуме в секундах
birthDate - дата рождения в секундах от начала эпохи UNIX
groupTitle - название группы
registered - дата регистрации на форуме (для гл. админа момент создания форума) в секундах от начала эпохи UNIX
inviteCode - код инвайта
respectPlus - кол-во плюсов полученных участником, если значение положит. то без плюса, но если отриц. - то минус указать
respectMinus - кол-во минусов полученных участником, если значение положит. то без плюса, но если отриц. - то минус указать
positivePlus - кол-во плюсов данных участником, если значение положит. то без плюса, но если отриц. - то минус указать
positiveMinus - кол-во минусов полученных участником, если значение положит. то без плюса, но если отриц. - то минус указать

Получение только нужных данных
Это возможно при использовании доп. аргументов со значением 1.

Примеры:
Запрос:

http://forum.mybb.ru/api.php?data=user&login=Наивная&id=1

Ответ:

{"id":"16793"}

Запрос:

http://forum.mybb.ru/api.php?data=user&login=Deff&groupId=1&positivePlus=1

Ответ:

{"groupId":"Опытные","positivePlus":"704"}

Я не эгоист!
Я предлагаю то, что будет востребовано в большинстве скриптов.

Например так:

http://forum.mybb.ru/api.php?data=user&id=5&login=1&avatar=1&status=1

Ромыч сможет получить часть нужной инфы для скрипта показывающего кто оценил пост.
Ответ запроса будет таким:

{"login" : "Борис Николаевич Ельцин" , "avatar" : "/img/avatars/******.jpg", "status" : "Экс-Президент"}

Для этого необходимо получить id-шники тех, кто оценил пост.
А как получить список id тех, кто оценил пост, а также данные ими оценки, и дату/время оценки я расскажу попозже.

А я разве закончил описание API? Всё ещё впереди! 

Развитый API - отличная возможность реализовать свои идеи для всех тех, кто пишет собственные приложения (скрипты) 

Deff, я тоже жду сообщения Admin'а о том, каким ему видится API.
Собственно за не имением такой опоры, пишу как думаю сам...

В моём представлении это функции/классы, находящиеся в файле api.php, и получающие данные путём get-запросов.
Далее функции/классы, в соответствии с полученными данными, делают запросы к БД и получают из таблиц БД инфу, которую преобразовывают в формат JSON и отдают клиенту т.е. браузеру.

Я пытаюсь создаю простую и понятную спецификацию запросов и ответов.
Это попытка создать решение удобное:
1. для реализации Admin'ом,
2. для использования программистами скриптов.

<script type="text/javascript">
$.getJSON("api.php", { data: "forum", title: "1" }, function(json) {
       var title_forum=json.title;
      //и далее манипуляции...
    });
</script>

На этом форуме этот запрос вернул бы "Единый форум поддержки". 

Дык я так и хочу. Я уже описал две части:
первое  - доступ к инфе о форуме,
второе - доступ к инфе юзеров.

Остальное напишу в течении нескольких дней.
API конструировать - не орешки щелкать.
Тем более первый раз таким занимаюсь 

mkusher, кстати, конструктивные предложения очень нужны

Впереди: списки юзеров, нтмл-контент, ЛС, опросы, рейтинг поста...

Admin, большое спасибо за отзыв
Я сам немного программист (не по образованию, а скорее по призванию) - в 2007-2009 годах писал программы на заказ, фриласером был. Клиенты прислали мне в общей сложности десятки тех. заданий. Поэтому знаю как написать хорошее ТЗ для программиста.
Ясное, подробное ТЗ это действительно полработы.

Кстати, вроде бы баг движка форума обнаружил: подробности.

Важное дополнение к API:

Необязательные параметры запросов.

1. Получение данных о времени с учётом часового пояса участника форума

Аргумент -> umt аббр.  User Mean Time (пользовательский часовой пояс)
Значение -> 0 или 1

Семантика:

При запросе инфы, вид которой определён через data, если в результатах ответа есть данные о времени (в формате кол-ва сек с начала эпохи UNIX), то они указываются так:

Для зарегистрированных и авторизованных пользователей:

Если umt не указан явно или равен 0, то в ответе данные о времени - с учётом часового пояса форума,
если umt=1, то данные о времени - в соответствии с часовым поясом участника форума, выставленного в профиле.

Для неавторизованных пользователей, т.е. для гостей:
Вне зависимости от значения umt или при не указании его в запросе: в ответе данные о времени - с учётом часового пояса форума.

Пример:
В настройках форума +03:00
В настройках профиля юзера +07:00

Авторизованный юзер:
Запрос:

http://forum.mybb.ru/api.php?data=forum&timeCreate=1&umt=1

Ответ:

{"timeCreate":"1331779622"}

Гость:
Запрос:

http://forum.mybb.ru/api.php?data=forum&timeCreate=1&umt=1

Ответ:

{"timeCreate":"1331765222"}

Т.е. для гостя - на 4 часа (14400 сек) меньше по сравнению с юзером.

2. Кеширование результатов запросов

Не знаю получится ли это реализовать, но по многим запросам не нужно каждый раз вытягивать инфу из БД.
Для снижения нагрузки API на серверы (экономия трафика, кол-ва подключений к БД и прочее) удобно кешировать ответы запросов.

Аргумент -> cache
Значение -> время (в секундах) актуальности кешированных данных

Если cache явно не задан или задан равным нулю, то данные не кешируются.

Пример:
Запрос:

http://forum.mybb.ru/api.php?data=forum&title=1&cache=86400

Ответ, сохраняется в кеше браузера на 86400 сек, т.е. на одни сутки:

{"title":"Единый форум поддержки"}

И повторные запросы в течениии суток будут брать результаты из кеша браузера, а не обращаться вновь в серверам МуВВ.

Думаю, реализовать это можно через заголовок ответа сервера:

$expires=htmlentities($_REQUEST['cache'], ENT_QUOTES, 'UTF-8');

header('Content-type: application/json');

if($expires != '' || $expires != 0)
  header('Expires: ' . gmdate('D, d M Y H:i:s', time() + $expires) . 'GMT');
else
{
  header("Cache-Control: no-store, no-cache, must-revalidate");
  header("Cache-Control: post-check=0, pre-check=0", false);
  header("Pragma: no-cache");
}

//-----
P.S.: сегодня мотался по магазинам - покупал межкомнатную дверь, поэтому устал, мозг не шибко варит и c описанием API могут быть задержки.

Отредактировано RUSSIAN_GOBLIN (Чт, 15 Мар 2012 14:28:18)

Deff, можно в заголовке ответа писать по умолчанию (если cash не указан или равен 0):

// HTTP/1.1
header("Cache-Control: no-store, no-cache, must-revalidate");
header("Cache-Control: post-check=0, pre-check=0", false);

// HTTP/1.0
header("Pragma: no-cache");

Или в функции запроса так:

<script type="text/javascript">
$.getJSON("api.php", { data: "forum", title: "1", "no-cache", Math.round(new Date().getTime()) }, function(json) {
       var title_forum=json.title;
      //и далее манипуляции...
    });
</script>

Серверный вариант предпочтительней.