ВАЖНО PublicAPI

[quiu]

Привет. Недавно мы выпустили публичный API нашего проекта. Здесь будет небольшой гайд по тому как её использовать.

Документация по API
- Redoc: https://api.agerapvp.club/redoc.html
- Swagger: https://api.agerapvp.club/swagger-ui/index.html

В этой статье рассмотрим самый простой пример использования API, получим профиль пользователя.

Для начала надо создать API ключ на сервере с помощью команды /api. Важно учесть что ключ можно создать если вы проиграли не сервере в сумме больше 10 часов. После выполнения вы получите ключ формата UUID v4 (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx), (8-4-4-4-12). Выглядеть он будет примерно вот так 907cbf06-9dd2-4564-844b-b5d5d16fb402.

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

Для этого нужно сделать GET запрос на https://api.agerapvp.club/v1/player/profile/{name}

Где {name} можно указать как ник игрока так и его ID.

Для тестов будем использовать curl

curl --header "X-Api-Key: 907cbf06-9dd2-4564-844b-b5d5d16fb402" https://api.agerapvp.club/v1/player/profile/quiu

После выполнения команды получим вот такой ответ:

{
  "currentServer": "null",
  "displayName": "§f§l☃ quiu",
  "language": "ENGLISH",
  "lastLogin": 192266019,
  "online": true,
  "ranks": [
    {
      "expire": -1,
      "id": 7563,
      "name": "DEVELOPER"
    }
  ],
  "skin": {
    "name": "quiu",
    "signature": "ZSCtLxGsSIBUWUniyOuwhZmuTzD7GiOVr32bbIDXjag0xYH+crkgcSgRxWh9NpRWvl6tmd+7cxRwEMuK0gElj+Re7Ubw0Yqj5RAQYLZjfEDjMDvTprswwwLKVmwPD+3wUM4ACUIDQqjLshzYhCNTfc6U3kuWKCduUOYysdzOu8os77/50b07oFPnm7eJnI9mWCZCp6Peon+lNVasaJ7sG878DZAWvupm7Xcz3iLddGCfSM2FpA2WLiJkmbn+6EvAD7FaXRSHniI1W0t/pJoeJxb59jpPTcOu9yPAbhD0Hbt0cDeBvVT52aOhsaVtuYpcYniWkj+7NhbLkbfL98WLuk6IsxrXkWyufiVswfjjwdYe/H0qSNwhB5T8EE/FRphPlgmmOF3sZ4XltSPO4j1JDKOISqamQEGDTCY737vqpXJr42dt65mJYdeLIwkxtEak7a21sWKTK7MnlRxmmye99FFMqodJcUNw4WgPx43rcBGHlhMaW7JqiKKIa6D7d9aKYjUSxH43x54cajQDVoNH3qyUXNKGWwI0H1KQQZXOdszwWltQSUwO6niNa3QXCcYriJnjMfostmc7Oh5V20ZNzOPEQ/qgccNljRpjCWPiGj1t8bvgz1L9eSRQGLfdINgn55IG3/zFIw1XyBB60mFA0FLQD7IK06LJ7EkASPw/sg8=",
    "uuid": "f12dc326df8a468c891db3b1d68056c7",
    "value": "ewogICJ0aW1lc3RhbXAiIDogMTc2NjI2MDU1ODcyNCwKICAicHJvZmlsZUlkIiA6ICJmMTJkYzMyNmRmOGE0NjhjODkxZGIzYjFkNjgwNTZjNyIsCiAgInByb2ZpbGVOYW1lIiA6ICJxdWl1IiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlL2U0NDVjMzBiMDI2NGE3NDIzMDZiMTYwMTZmNjUyNTdkNjRlMzhjZGViMjUxNWJhZjg3N2FlODI4ODVlMWIzYzAiLAogICAgICAibWV0YWRhdGEiIDogewogICAgICAgICJtb2RlbCIgOiAic2xpbSIKICAgICAgfQogICAgfSwKICAgICJDQVBFIiA6IHsKICAgICAgInVybCIgOiAiaHR0cDovL3RleHR1cmVzLm1pbmVjcmFmdC5uZXQvdGV4dHVyZS9jYjQwYTkyZTMyYjU3ZmQ3MzJhMDBmYzMyNWU3YWZiMDBhN2NhNzQ5MzZhZDUwZDhlODYwMTUyZTQ4MmNmYmRlIgogICAgfQogIH0KfQ=="
  },
  "userId": 6,
  "username": "quiu"
}

В ответе ещё есть данные о скине, мы так же подняли свой сервис для работы со скинами, статья как его использовать: https://forum.agerapvp.club/threads/skin-service.347/

Так же есть эндпоинт для тестирования корректности составления запроса: /v1/test

curl --header "X-Api-Key: 907cbf06-9dd2-4564-844b-b5d5d16fb402" https://api.agerapvp.club/v1/test

Ответ будем выглядеть следующим образом:

{
  "success": true,
  "message": "Looks like everything is working yey"
}

Ещё важным пунктом является то что все ответы кешируются на некоторое время.В случае если это лёгкий запрос типо получения профиля, ответ будет закеширован на 10 секунд, однако если это более сложный запрос например генерация топа то ответ будет закеширован на 10 минут

На этом думаю можно закончить так как от метода к методу логика запросов не менятся.

 

[ImCluzzy]

Public API 1.6.0: гильдии и приватные профили​

Всем привет! Вышло обновление Public API. Рассказываем, что изменилось.

Гильдии
Добавили пять новых методов. Через них можно получить всё, что видно о гильдиях в игре:

• GET /v1/guild/info/{название} - информация о гильдии по названию или тегу
• GET /v1/guild/player/{ник} - гильдия, в которой состоит игрок
• GET /v1/guild/members/{название} - участники: ранг, дата вступления, сколько опыта принесли гильдии
• GET /v1/guild/wars/{название}?limit=20 - история кланваров: соперник, режим, ставка, счёт и итог (до 50 последних)
• GET /v1/guild/top/{level|wars}?limit=10 - топ гильдий по уровню или по победам в кланварах (до 100 мест)

Ответ /v1/guild/info/PRIME:

{
  "id": 6,
  "name": "PRIME",
  "tag": "PRIME",
  "color": "9",
  "secondaryColor": "",
  "bold": true,
  "level": 1,
  "experience": 1396,
  "levelProgress": 1396,
  "nextLevelExperience": 10000,
  "members": 6,
  "slots": 10,
  "ownerName": "Agera001",
  "createdAt": 1793051898,
  "warWins": 1,
  "warLosses": 1
}

Ответ /v1/guild/top/level?limit=3:

{
  "type": "level",
  "entries": [
    { "position": 1, "name": "TrustNoBody", "tag": "TNB", "color": "c", "level": 4, "value": 41223 },
    { "position": 2, "name": "REASONS", "tag": "RSN", "color": "9", "level": 3, "value": 27405 },
    { "position": 3, "name": "kiss", "tag": "KISS", "color": "4", "level": 3, "value": 25472 }
  ]
}

Что важно знать:

• color и secondaryColor - коды цветов Minecraft (0-9, a-f). Пустой secondaryColor значит, что тег целиком одного цвета
• value в топе - опыт для level и число побед для wars
• время везде в Unix-секундах
• если гильдия не найдена или игрок не состоит в гильдии, придёт 404 с кодом GUILD_NOT_FOUND
• данные гильдий обновляются раз в 10 секунд, топы - раз в 10 минут

Приватные профили
Если игрок запретил просмотр профиля в настройках, GET /v1/player/profile/{ник} теперь отвечает 403 с кодом PLAYER_PROFILE_PRIVATE. Данные профиля в этом случае не отдаются. Обработайте этот ответ у себя - например, показывайте «Профиль скрыт».

Как начать

1. Получите ключ командой /apikey в игре (нужно наиграть 10 часов)
2. Передавайте его в каждом запросе в заголовке X-Api-Key
3. Проверьте, что всё работает: GET https://api.agerapvp.club/v1/test

Документация со всеми методами и полями:

• Redoc: https://api.agerapvp.club/docs
• Swagger: https://api.agerapvp.club/swagger-docs