API

Проект «Мафия онлайн» предоставляет интерфейс для получения из БД некоторой информации, которая может оказаться полезной для создания различных сторонних приложений. Данный интерфейс нельзя назвать API в классическом смысле этого слова, т.к. готовых библиотек классов и функций пока нет. Однако всё необходимое для получения информации с сервера здесь будет описано. Обёртка представленной здесь информации в код на вашем любимом языке программирования остаётся лишь делом техники. Поэтому, с поправкой на вышесказанное, будем гордо наименовать данный документ полным «справочником» по API «Мафии онлайн». 🙂

Актуальная на данный момент версия — 0.9.4 (27.02.2013)

Запрос к API

Для выполнения запроса к API необходимо осуществить вызов скрипта http://mafiaweb.ru/api/api.php, которому методом GET необходимо передать следующие аргументы:

  • action* — вызываемый метод API;
  • format* — формат выходных данных (plain либо json)
  • param — необязательный параметр, используется в некоторых методах в качестве аргумента.

Ответ API

На данный момент API предоставляет информацию в форматах Plain Text (DSV) и JSON.
Nota bene! Ответы в формате DSV более не поддерживаются и не развиваются. Все новые фичи отныне будут добавляться только в формате JSON. При разработке не стоит полагаться на продолжение поддержки данных в DSV. Отныне все эти методы должны восприниматься как deprecated и могут быть удалены в любой момент.

При запросе к API обязательно явное указание формата выходных данных (format=plain либо format=json).
Все выходные данные выдаются в кодировке utf-8.

  • DSV
    Выходные данные разбиты на строки, разделённые символом перевода строки Unix-EOL (он же LF, он же 0x0A, он же #10, он же \n). Значения внутри строки разделяются символом | («pipe», вертикальная черта).
  • JSON
    Возвращается валидная JSON-строка, сгенерированная функцией json_encode().

Доступные методы API

  • action=ver
    Возвращает информацию о текущей версии API.
  • action=userlist
    Возвращает список незаблокированных пользователей, достигших первого уровня, вместе с их ID.
  • action=info
    В качестве параметра param= принимает ник игрока.Возвращает информацию об игроке: id, уровень, точное написание ника, пол, дату регистрации, значок Авторитета, значок семьи, текущее расположение (локацию), дату рождения (только в JSON), информацию о статистике игрока (С-В-П, кол-во очков, рейтинг), информацию о текущем наказании игрока (только в JSON). Если такого игрока не существует, выводится соответствующее сообщение.

    Дополнительные опции конфигурации (только в JSON):

    • возможен запрос без получения статистики — для этого к запросу нужно добавить параметр stat=no
    • возможно запросить содержимое дополнительной информации о персонаже — для этого к запросу нужно добавить параметр i=yes
    • возможно запросить сумеречные «статы» игрока — для этого к запросу нужно добавить параметр s=yes; если игрок в паспорте — все статы будут возвращены равными -1
  • action=avt
    • param=list (только json)
      Возвращает список Авторитетов: id персонажа, пол, ник, id отдела, ранг внутри отдела (цифрой от 1 до 6), имя файла значка (относительно http://mafiaweb.ru/images/moder/), текущую локацию Авторитета, текст должности — и отделов (парами id — название).
  • action=fam
    • param=list
      Возвращает список семей и заявок на регистрацию (id семьи, дата регистрации, название, URL-адрес сайта, id значка семьи, состояние заявки, id персонажа Главы семьи, тип (расширение) значка)
    • param=members (в варианте plain)
      Возвращает список всех игроков, состоящих в семьях (id персонажа, ник персонажа, id семьи, дату вступления, должность в семье)
    • param=members (в варианте json)
      Возвращает список игроков, состоящих в семье, id которой передан посредством параметра id. При передаче неверного параметра выводится соответствующее сообщение.
  • action=log
    • param=info (только json)
      Принимает номер партии в качестве аргумента id=.
      Возвращает краткую информацию о партии: id, дату и время завершения (UNIX timestamp), локацию партии, флаг VIP-клуба, результат партии, массив игроков партии: состояние игрока на конец партии, роль, ник игрока, id игрока (либо -1, если он был в паспорте), пол
    • param=log (только json)
      Принимает номер партии в качестве аргумента id=. Возвращает полную информацию о партии: то же, что и предыдущий метод, плюс краткий лог игры и полный лог чата.
    • param=list
      Принимает в качестве аргумента date= дату в формате YYYYMMDD.
      Возвращает список партий, сыгранных в указанную дату. Данные по каждой партии аналогичны методу param=info, за исключением списка игроков.
    • param=current (только json)
      Не принимает аргументов. Возвращает список текущих партий: id, дату и время начала, локацию правил партии, признак VIP-клуба, массив словарей «id игрока – ник» (если игрок использует поддельный паспорт, в качестве id будет значение -1).
  • action=stats
    Возвращает статистику сервера: количество зарегистрированных незаблокированных пользователей; количество сыгранных партий (всего, побед мафии, побед честных, ничьих, остановленных); количество игроков онлайн в данный момент.