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żka	Uprawnienie	Opis
GET	`/api/v1/health`	—	Status mostu
GET	`/api/v1/server`	`listings.read`	Gracze online, wersje
GET	`/api/v1/listings`	`listings.read`	Paginowane oferty
GET	`/api/v1/listings/{id}`	`listings.read`	Jedna oferta
GET	`/api/v1/categories`	`categories.read`	Kategorie z GrzybcioRynku
GET	`/api/v1/stats`	`stats.read`	Statystyki z cache
GET	`/api/v1/history`	`history.read`	Publiczna historia transakcji
GET	`/api/v1/price-history/{item}`	`history.read`	Punkty do wykresu cen
GET	`/api/v1/players/{uuid\|name}`	`players.read`	Profil publiczny gracza
GET	`/api/v1/players/{id}/listings`	`players.read`	Oferty konkretnego gracza
GET	`/api/v1/sellers`	`players.read`	Unikalne nicki sprzedawców
GET	`/api/v1/events`	`listings.read`	Strumień SSE
GET	`/api/docs`	—	Dokumentacja HTML
GET	`/api/openapi.json`	—	OpenAPI 3

Endpointy zapisu

Metoda	Ścieżka	Odpowiedź w v1
POST	`/api/v1/listings`	`403 WRITE_NOT_ENABLED`
DELETE	`/api/v1/listings/{id}`	`403 WRITE_NOT_ENABLED`
POST	`/api/v1/transactions`	`403 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

Parametr	Typ	Opis
`page`	liczba	Numer strony
`limit`	liczba	Ile wyników, maksymalnie `api.max-limit` (domyślnie 100)
`offset`	liczba	Alternatywa dla `page`
`search`	tekst	Wyszukiwanie po nazwie przedmiotu
`category`	tekst	Filtr po kategorii
`sort`	tekst	Np. `price_asc`, `CHEAPEST`
`minPrice`	liczba	Dolna granica ceny
`maxPrice`	liczba	Górna granica ceny
`seller`	tekst	Filtr po sprzedawcy
`itemType`	tekst	`all`, `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.

On this page