Grzybcio Wiki

Endpointy REST

Pełna lista ścieżek /api/v1 z wymaganymi uprawnieniami, parametrami i przykładami.

Prefiks wszystkich ścieżek: /api/v1. Dokumentacja generowana automatycznie dostępna jest pod /api/docs, a specyfikacja pod /api/openapi.json.

Pełna lista

MetodaŚcieżkaUprawnienieOpis
GET/api/v1/health—Status mostu
GET/api/v1/serverlistings.readGracze online, wersje
GET/api/v1/listingslistings.readPaginowane oferty
GET/api/v1/listings/{id}listings.readJedna oferta
GET/api/v1/categoriescategories.readKategorie z GrzybcioRynku
GET/api/v1/statsstats.readStatystyki z cache
GET/api/v1/historyhistory.readPubliczna historia transakcji
GET/api/v1/price-history/{item}history.readPunkty do wykresu cen
GET/api/v1/players/{uuid|name}players.readProfil publiczny gracza
GET/api/v1/players/{id}/listingsplayers.readOferty konkretnego gracza
GET/api/v1/sellersplayers.readUnikalne nicki sprzedawców
GET/api/v1/eventslistings.readStrumień SSE
GET/api/docs—Dokumentacja HTML
GET/api/openapi.json—OpenAPI 3

Endpointy zapisu

MetodaŚcieżkaOdpowiedź w v1
POST/api/v1/listings403 WRITE_NOT_ENABLED
DELETE/api/v1/listings/{id}403 WRITE_NOT_ENABLED
POST/api/v1/transactions403 WRITE_NOT_ENABLED

Istnieją, ale zawsze odrzucają — most jest z założenia tylko do odczytu.

/api/v1/health

Jedyny endpoint, który nadaje się do monitoringu — nie wymaga klucza i nie obciąża serwera gry.

curl http://127.0.0.1:8765/api/v1/health

Dobry cel dla uptime monitora

Jeśli używasz zewnętrznego monitoringu (UptimeRobot, Better Stack), ustaw go właśnie na ten adres. Nie potrzebuje klucza, a jego odpowiedź mówi, czy most żyje.

/api/v1/listings

Najczęściej używany endpoint. Zwraca paginowaną listę ofert.

GET /api/v1/listings?page=1&limit=24&search=diamond&category=BLOCKS&sort=price_asc&minPrice=100&maxPrice=10000

Parametry

ParametrTypOpis
pageliczbaNumer strony
limitliczbaIle wyników, maksymalnie api.max-limit (domyślnie 100)
offsetliczbaAlternatywa dla page
searchtekstWyszukiwanie po nazwie przedmiotu
categorytekstFiltr po kategorii
sorttekstNp. price_asc, CHEAPEST
minPriceliczbaDolna granica ceny
maxPriceliczbaGórna granica ceny
sellertekstFiltr po sprzedawcy
itemTypetekstall, vanilla, nexo, oraxen, custom

limit ma twardy sufit

Podanie limit=5000 nie zwróci pięciu tysięcy ofert — most przytnie wartość do api.max-limit. Do pobrania większej liczby danych stronicuj przez page.

Przykład

curl -H "X-API-Key: twoj-klucz" \
  "http://127.0.0.1:8765/api/v1/listings?limit=10&sort=price_asc"

/api/v1/players/{uuid|name}

Przyjmuje zarówno UUID, jak i nick:

curl -H "X-API-Key: twoj-klucz" \
  "http://127.0.0.1:8765/api/v1/players/Grzybcio"

Zwraca publiczny profil — to, co i tak widać na rynku w grze. Nie ma tam nic prywatnego.

/api/v1/price-history/{item}

Punkty do wykresu ceny konkretnego przedmiotu w czasie. Cache domyślnie 30 sekund, bo wykres nie musi być świeży co do sekundy.

/api/v1/categories i /api/v1/sellers

Lekkie endpointy pomocnicze — lista kategorii z rynku oraz unikalne nicki sprzedawców. Przydają się do zbudowania filtrów na stronie.

Format błędów

{
  "error": {
    "code": "LISTING_NOT_FOUND",
    "message": "Listing does not exist.",
    "status": 404
  }
}

Kody HTTP: 400, 401, 403, 404, 429, 500, 503.

Testowanie z konsoli

# health — bez klucza
curl http://127.0.0.1:8765/api/v1/health

# oferty — z kluczem w nagłówku
curl -H "X-API-Key: twoj-klucz" http://127.0.0.1:8765/api/v1/listings?limit=3

# to samo, ale przez Authorization
curl -H "Authorization: Bearer twoj-klucz" http://127.0.0.1:8765/api/v1/stats

# sprawdzenie nagłówków limitów
curl -i -H "X-API-Key: twoj-klucz" http://127.0.0.1:8765/api/v1/categories

Zobacz też dokumentację generowaną z kodu

/api/docs zawsze odpowiada temu, co faktycznie robi twoja wersja mostu. Ta strona opisuje wersję 1.0.0 — jeśli masz nowszą, ufaj /api/docs.

Na tej stronie

Pełna listaEndpointy zapisu/api/v1/health/api/v1/listingsParametryPrzykład/api/v1/players/{uuid|name}/api/v1/price-history/{item}/api/v1/categories i /api/v1/sellersFormat błędówTestowanie z konsoli