API

Материал из GreenCubes Wiki
Версия от 01:32, 3 июля 2020; DragonFire (обсуждение | вклад)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)
Перейти к навигации Перейти к поиску

GreenCubes API — официальный Web-API созданный для упрощения доступа к такой информации как: дату регистрации, последний вход игрока на всех серверах, его префикс и цвет его, цвет ника, URL ника и правильный ник. Количество игроков на определённом сервере и состояние сервера.

Также API предоставляет авторизацию через OAuth 2.0.

Разработчиком API является Kernel.

Общая информация[править]

Формат времени[править]

Время выводится по GMT+0. Любое время в API выводится в формате POSIX (он же Timestamp).

Rate Limit[править]

В API действует ограничение на 500 запросов для неавторизованного и 5000 запросов для авторизованного пользователя в час с одного IP адреса. Получить информацию о текущем количестве доступных запросов можно отправив запрос на /rate_limit. Подробнее в разделе Rate Limit API.

Авторизация[править]

Сервер API предоставляет авторизацию через протокол OAuth 2.0 и через обычную авторизацию. Авторизация требуется только для метода /user и служит скорее для предоставления базовой авторизации через GreenCubes для сторонних приложений.

Базовая авторизация[править]

Нужно сделать POST запрос на /login, получив ошибку или Success, мы получаем доступ к защищённым API.

Для выхода используйте GET /logout

OAuth 2.0 – Server-flow[править]

Тут описывается случай, когда вы авторизуетесь с веб-сервера, а не мобильного приложения.
Для начала клиент делает GET запрос на /oauth/authorize со следующими параметрами: 

client_id=2
redirect_uri=http://example.doge/oauth/callback
response_type=code

Где client_id - это ID вашего приложения на OAuth сервере, а redirect_uri - это адрес куда впоследствии вышлется код для получения токена. В зависимости от того, залогинен ли пользователь или нет, он вернёт нам одну из следующих страниц:

  • Форма логина

    Форма логина

  • Спрашиваем у пользователя разрешение на использование его данных

    Спрашиваем у пользователя разрешение на использование его данных

После нажатия на "Разрешить", страница отправляет запрос на /oauth/authorize/decision, после чего сервер отвечает запросом с единственным параметром на заданный redirect_uri: 

code=w88RMIrSxJdvMmX1hb6DAGHBG2RLUsS8

Теперь же ваш сервер должен отправить POST запрос на /oauth/access_token следующего вида: 

client_id=2
client_secret=wowsecurepasswd
code=w88RMIrSxJdvMmX1hb6DAGHBG2RLUsS8
grant_type=authorization_code
redirect_uri=http://example.doge/oauth/callback

Если всё хорошо, то в ответ он получит JSON следующего вида: 

{
    "access_token": {
        "token": "47TbwmOFnUiXTVkTvh2an2KPcuD4xEzVObZZfs...06ylygeFxUVyPjWkkvTCEL8A0hDbSRju9",
        "userId": 95671,
        "username": "Kernel",
        "clientId": 2,
        "scope": "profile,email"
    },
    "token_type": "bearer"
}

Теперь вы можете использовать полученный token для доступа к защищённым частям API, например, /user

  • access_token — Объект с access_token.
    • token — Токен авторизации. Примечание: Токен только тут имеет идентификатор token в дальнейшем при авторизации его нужно отсылать как access_token.
    • userId – ID пользователя в системе.
    • username — Имя пользователя для которого выдан access_token.
    • clientId — Числовой идентификатор приложения.
    • scope — Выданные права доступа. Как правило, это только profile, email и regions
  • token_type — Тип токена. Может быть только bearer. Введение других типов токенов не планируется.


OAuth 2.0 – Client-flow (Implicit Flow)[править]

Тут описывается случай, когда вы авторизуетесь из мобильного/браузерного клиентского приложения (без сервера), а не серверного приложения.
Для начала клиент делает GET запрос на /oauth/authorize со следующими параметрами: 

client_id=2
redirect_uri=http://example.doge/oauth/callback
response_type=token

Где client_id - это ID вашего приложения на OAuth сервере, а redirect_uri - это адрес на который будет впоследствии передан access_token. В зависимости от того, залогинен ли пользователь или нет, он вернёт нам одну из следующих страниц:

  • Форма логина

    Форма логина

  • Спрашиваем у пользователя разрешение на использование его данных

    Спрашиваем у пользователя разрешение на использование его данных

Если Вы разрабатываете браузерное Javascript-приложение (обращаетесь к API с внешнего сайта), необходимо указывать ссылку в рамках домена, указанного в настройках приложения. В остальных случаях в качестве redirect_uri нужно использовать адрес https://api.greencubes.org/blank.html.


После нажатия на "Разрешить", страница отправляет запрос на /oauth/authorize/decision, после чего сервер, если всё конечно хорошо, отвечает перенаправлением с двумя параметрами в hash URL на заданный redirect_uri: 

access_token=w88RMIrSxJdvMmX1hb6DAGHBG2RLUsS8
token_type=Bearer

Соответственно, адрес будет выглядеть примерно так:
http://example.doge/oauth/callback#access_token=w88RMIrSxJdvMmX1hb6DAGHBG2RLUsS8&token_type=Bearer.

Теперь вы можете использовать полученный access_token для доступа к защищённым частям API, например, /user

  • access_token — Токен авторизации.
  • token_type – Тип токена. В данный момент, строго только Bearer.

Встраивание страниц авторизации[править]

Сервер отдаёт заголовок X-Frame-Options: DENY, что запрещает встраивание страниц авторизации в фреймы. Рекомендовано открывать страницы авторизации в новых окнах.

Описание всех API[править]

На данный момент существует семь API:

  • User API — Основная информация об игроке: дата регистрации, последний вход игрока на всех серверах, префикс и цвет его, цвет ника, URL скина и никнейм с правильным регистром.
  • Organization API – Основная информация об организации: ID, тег, название, "под-название" оно же "тип".
  • GC.Main API — API Main сервера. Состояние сервера и количество игроков. Статистика по экономике (редирект на api.php).
  • GC.RPG API — API RPG сервера. Состояние сервера и количество игроков.
  • GC.Apocalyptic — API Apocalyptic сервера. Состояние сервера и количество игроков.
  • Meta API — Информация о Web-API: текущая версия, адрес документации, авторы.
  • Rate Limit API — Информация о лимите запросов для текущего IP.

User API[править]

GET  /users/:user

Основная информация о пользователе:

  • id – ID пользователя в системе.
  • username — Правильный ник (с правильным регистром).
  • status — Статус онлайна игрока на всех серверах.
  • lastseen — Последний вход игрока на все сервера. Если не входил на сервер, то вместо значения будет null.
  • reg_date — Дата регистрации.
  • prefix — Префикс с цветами ников.
  • nick_color — Цвет ника.
  • skin_url — Адрес скина игрока. Внимание! Выводится вне зависимости от наличия у игрока скина. Если у игрока нет скина, то сервер отдаёт 404.
  • cape_url — Адрес плаща игрока. Внимание! Выводится вне зависимости от наличия у игрока плаща. Если у игрока нет плаща, то сервер отдаёт 404.
  • banned — Статус бана игрока.
  • bannedTill — Время до которого игрок забанен. Внимание! Выводится только, если у игрока временный бан. В противном случае, его не будет в ответе от сервера.
  • badges — Массив данных о значках:
    • badgeId — Идентификатор предмета (значка).
    • badgeData — Метадата предмета (значка). (например, 4100,4, где 4100 это Id, а 4 это метадата)
    • first — Дата первого скрафченного такого значка.
    • count — Количество таких скрафченных значков.

Внимание! Некоторые цвета могут иметь номер не в шестнадцатиричном виде, а в виде одиночного номера. В таких случаях используются цвета из базового раздела донатных цветных ников.[1]

Паттерн для отбрасывания цветов от Rena4k-и: &([0-9a-fA-F])|&([usipg])|&(r[0-9a-z]{8}) 

{
  "id": 1,
  "username": "Rena4ka",
  "status": 
  { 
    "main": true, 
    "rpg": false, 
    "apocalyptic": false 
  },
  "lastseen":
  {
    "main": 1394924190,
    "rpg": 1394924190,
    "apocalyptic": 1394924190
  },
  "reg_date": 1295000171,
  "prefix": "&r99446666[&rff66c016G&rfff7f7f7C&r99446666]&f ",
  "nick_color": "rffea8df7",
  "skin_url": "http://greenusercontent.net/mc/skins/Rena4ka.png",
  "banned": true,
  "bannedTill": 1404858798,
  "badges": [
     {
      "badgeId": 4100,
      "badgeData": 5,
      "first": 1406848657,
      "count": 1
    }
  ]
}
GET /user

Тело запроса: 

access_token=47TbwmOFnUiXTVkTvh2an2KPcuD4xEzVObZZfs...ЭТОПРИМЕРEL8A0hDbSRju9

Основная информация о текущем пользователе. Для успешного запроса вам потребуется ваш OAuth access_token (см. раздел авторизация).

Ответ от сервера такой же как и у GET /users/:user. 

GET /user/regions

Тело запроса: 

access_token=47TbwmOFnUiXTVkTvh2an2KPcuD4xEzVObZZfs...ЭТОПРИМЕРEL8A0hDbSRju9

Список регионов, в которых текущий пользователь имеет права (не только full или build, например). 

[
  {
    "name": "BaronHome_KernCastle",
    "rights": [
      "full",
      "build"
    ],
    "coordinates": {
      "first": "-1305 10 -656",
      "second": "-1158 127 -577"
    }
  },
  {
    "name": "Nilahn",
    "rights": [
      "build-child",
      "build"
    ],
    "coordinates": {
      "first": "-3303 0 -663",
      "second": "-3076 127 -328"
    }
  }
]

Organization API[править]

GET /organizations/:organizationId
  • id – Идентификатор организации в системе.
  • tag – Тег.
  • title – Название.
  • subtitle – "Под-название" оно же "тип" организации.
{
  "id": 1,
  "tag": "cats",
  "title": "Кисоньки",
  "subtitle": "Overmind",
  "url": "https://greencubes.org/org/1"
}

GC.Main API[править]

GET /main/status
  • server — Название сервера.
  • status — Статус работы сервера (онлайн или нет).
  • online — Количество игроков онлайн.
{
  "server": "Main",
  "status": true,
  "online": 146
}
GET /main/online

Отдаёт список игроков, которые сейчас на сервере. За исключением Модераторов и Команды ГК. 

[
  "avtovaz",
  "beargrils7",
  "danik2003",
  "domainlocals",
  "milka56",
  "mumu", 
  "PH0ENIX",
  "redfox",
  "YOT"
]

GET /main/economy
  • status — Статус ответа. Значение status = 0 означает успешное получение данных. Любой другой статус является ошибкой.
  • dailymoney — Оборот зелени за последние сутки.
  • time — Актуальность данных.

Внимание! Актуальность данных не более 15 минут. 

{
  "economy": {
     "dailymoney": 3691909
  },
  "time": 1395183916
}
GET /main/named_colors
  • name — Название цвета на английском языке.
  • localizedName — Название цвета на русском языке.
  • h — Цветовой тон.
  • s — Насыщенность.
  • pioneer — Никнейм первооткрывателя.
  • opened — Время первого открытия.
  • secondPioneer — Никнейм второго открывшего.
  • repeated — Время второго открытия.
[
  {
    "name": "Pink",
    "localizedName": "Розовый",
    "h": 349,
    "s": 25,
    "pioneer": "SadKas",
    "opened": "2013-12-10T13:09:56.000Z",
    "secondPioneer": "Mopaxac",
    "repeated": "2013-12-28T16:17:31.000Z"
  }
]

Также существует версия в виде HTML-таблицы: /main/named_colors/html 

GET /main/items

Отдаёт список блоков. Аналог этой страницы. 

[
  {
    "id": 4,
    "data": 0,
    "key": "cube.cobblestone",
    "name": "Булыжник",
    "image_url": "https://greencubes.org/img/items/cobblestone.png"
  }
]

GET /main/regions/:name

Отдаёт информацию о регионе аналогичную внутриигровой команде /region info.

Внимание! В full_access и build_access: o:номер обозначает, что права есть у организации, однако это ВРЕМЕННЫЙ вывод для организации, и в будущем это будет изменено. Не стоит это использовать в приложениях на данный момент. all обозначает, то же самое, что и в игре - права есть у всех. 

{
  "name": "canterlot",
  "parent": "spawn_cities_protect",
  "flags":
  {
    "grow": 0,
    "blow": 0,
    "animals": 1 
  },
  "full_access": [
    "Favourite",
    "Rena4ka",
    "Drbadnick",
    "o:1482",
    "Medyza",
    "o:1344"
  ],
  "build_access":[
    "Djzero"
  ],
  "coordinates": {
    "first": "-8302 40 -1707",
    "second": "-7803 127 -1408"
  }
}

GC.RPG API[править]

GET /rpg/status
  • server — Название сервера.
  • status — Статус работы сервера (онлайн или нет).
  • online — Количество игроков онлайн.
{
  "server": "RPG",
  "status": true,
  "online": 42
}
GET /rpg/online

Отдаёт список игроков, которые сейчас на сервере. За исключением Модераторов и Команды ГК. 

[
  "avtovaz",
  "beargrils7",
  "danik2003",
  "domainlocals",
  "milka56",
  "mumu", 
  "PH0ENIX",
  "redfox",
  "YOT"
]


GC.Apocalyptic API[править]

GET /apocalyptic/status
  • server — Название сервера.
  • status — Статус работы сервера (онлайн или нет).
  • online — Количество игроков онлайн.
{
  "server": "Apocalyptic",
  "status": true,
  "online": 34
}
GET /apocalyptic/online

Отдаёт список игроков, которые сейчас на сервере. За исключением Модераторов и Команды ГК. 

[
  "avtovaz",
  "beargrils7",
  "danik2003",
  "domainlocals",
  "milka56",
  "mumu", 
  "PH0ENIX",
  "redfox",
  "YOT"
]


Meta API[править]

GET /meta
  • version — Текущая версия API. Значение после дефиса - текущий коммит в Git.
  • documentation_url — Адрес документации (эта страница).
  • authors — Авторы API.
    • name — Имя и фамилия. В скобках никнейм.
    • homepage_url — URL персонального сайта.
{
  "version": "0.1-603b241",
  "documentation_url": "https://wiki.greencubes.org/API",
  "authors":
  [
    {
      "name": "Arseniy Maximov (Kern0)",
      "homepage_url": "http://kern0.ru"
    }
  ]
}

Rate Limit API[править]

GET /rate_limit
  • limit — Общее ограничение по запросам в час.
  • remaining — Количество разрешённых запросов.
  • reset — Время в миллисекундах, когда сбросится счётчик.
{
  "limit": 1000,
  "remaining": 942,
  "reset": 1397625331
}

Также в каждом ответе от сервера есть HTTP заголовки вида: 

x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 1397625331

Виды ошибок сервера API[править]

Если что-то пошло не так, то сервер всегда может отдать ошибку соответствующую текущей проблеме.

Страница не существует[править]

Status: 404 Not Found
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 3007543

{
  "message": "Not Found",
  "documentation_url": "https://wiki.greencubes.org/API"
}

Требуется авторизация[править]

Местоположение: /user 

Status: 403 Forbidden
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 3007543

{
  "message": "Forbidden. Need authorization",
  "documentation_url": "https://wiki.greencubes.org/API"
}

Предоставленный access_token не имеет прав на данный scope[править]

Status: 403
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 3007543

{					 Forbidden
  "message": "Forbidden. Access token don't have access to this scope",
  "scope": "profile"
  "documentation_url": "https://wiki.greencubes.org/API"
}

Превышен лимит запросов[править]

Status: 429 Too Many Requests
x-ratelimit-limit: 1000
x-ratelimit-remaining: 0
x-ratelimit-reset: 3007543

{
  "message": 'Rate limit exceeded, retry later',
  "retry_in": 3007543,
  "documentation_url": "https://wiki.greencubes.org/API"
}

Виды ошибок сервера OAuth 2.0[править]

В запросе на авторизацию/получение токена не хватает определённого параметра[править]

Местоположение: GET /oauth/authorize 

Status: 400 Bad Request
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 1396741263

{
  "message": "missing_parameter is not defined",
  "documentation_url": "https://wiki.greencubes.org/API"
}

Вместо missing_parameter может быть:
GET /oauth/authorize:

  • client_id
  • redirect_uri

GET /oauth/token:

  • client_id
  • client_secret
  • code
  • grant_type
  • redirect_uri

Некорректный response_type в запросе на авторизацию[править]

Местоположение: GET /oauth/authorize 

Status: 400 Bad Request
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 1396741263

{
  "message": "Wrong response_type",
  "documentation_url": "https://wiki.greencubes.org/API"
}

Если используется уже использованный/неверный код получения токена[править]

Status: 500 Internal Server Error
Местоположение: POST /oauth/token 

x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 1396741263

{
  "error": "invalid_grant",
  "error_description": "invalid code"
}

Некорректный grant_type[править]

Местоположение: POST /oauth/token 

Status: 500 Internal Server Error
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 1396741263

{
  "error": "unsupported_grant_type",
  "error_description": "invalid grant type"
}

Примечания[править]

  1. ↑ Таблица с цветными никами из этого раздела.

См. Также[править]

п • о • р
GreenCubes
GreenCubes Main
История
Администрация
Веб-сервисы
Техническая часть
Источник — https://wiki.greencubes.org/index.php?title=API&oldid=2743