Julkinen API

Julkinen API antaa organisaation ylläpitäjille suoran HTTP-pääsyn organisaatiosi reaaliaikaisiin tietoihin — vedä ne mihin tahansa verkkosivustoon, sovellukseen, bottiin tai automaatioon, joka osaa tehdä HTTP-pyynnön. Se on Business-tilauksen ominaisuus.

Avain on rajattu organisaatioosi — kaikki päätepisteet toimivat automaattisesti kyseistä ryhmää vasten. Perus-URL: https://api.ludoya.com/public/v1. Todennusotsake: X-Api-Key: YOUR_KEY. Nopeusrajoitus: 100 pyyntöä minuutissa, minkä jälkeen saat vastauksen 429.

Avaimet alkavat merkeillä ldy_ ja ovat 36 merkkiä pitkiä, joten ne on helppo huomata asetustiedostosta — ja helppo etsiä, jos jokin päätyy joskus väärään paikkaan. Kohtele sitä kuin salasanaa: vain palvelinpuolella, ja peruuta se samalta sivulta, jos se vuotaa.

Mihin pääset käsiksi

• Sijainnit — ryhmäsi käytettävissä olevat tilat ja niiden paikat; käytetään syötteenä tapahtumia luotaessa
• Tapahtumat (luku) — tulevat ja menneet tapahtumat otsikoineen, kuvauksineen, päivämäärineen ja kellonaikoineen, aikavyöhykkeineen, kapasiteetteineen, osallistujamäärineen ja tiloineen
• Tapahtumat (kirjoitus) — luo ja päivitä tapahtumia POST- ja PUT-pyynnöillä, täydellä hallinnalla sijainnista, kapasiteetista, oikeuksista, näkyvyydestä ja kuvasta
• Alitapahtumat — listaa päätapahtuman sisällä olevat tapahtumat
• Osallistujat — lisää joku tapahtumaan, muuta hänen osallistumistaan tai poista hänet
• Jäsenet — jäsenlista käyttäjäprofiileineen ja rooleineen (Omistaja, Ylläpitäjä, Jäsen), sivutettuna
• Kutsut — kutsu joku ryhmääsi
• Haku — etsi Ludoyan käyttäjiä ja lautapeliluetteloa, jotta voit muuntaa nimet tunnisteiksi ennen kirjoittamista
• Kokoelma — pelikokoelma suodatuksineen omistuksen, nimen, pelaajamäärän ja listan mukaan; lajiteltavissa ja sivutettuna; jokainen peli sisältää BGG-metatiedot
• Tilastot — pelitilastot miltä tahansa ajanjaksolta: kokonaismäärät, keskiarvot, kärkipelaajat voittoineen ja pisteineen, erittelyt pelaajamäärän, sijainnin ja pelin mukaan
• Kampanjat (luku) — listaa ryhmän kampanjat jäsen- ja sessiomäärineen; hae kampanjan täydet tiedot jäsenineen, menneine sessioineen ja aikataulutettuine tapahtumineen
• Kampanjat (kirjoitus) — luo ryhmälle kampanjoita ja päivitä niiden nimi, kuvaus, tila ja näkyvyys
• Kampanjan jäsenet — lisää, päivitä ja poista kampanjassa olevia ihmisiä

Päätepisteet

GET /locations

Palauttaa ryhmän käytettävissä olevat sijainnit. Jokaisella sijainnilla on id, name, valinnainen address, capacity, isDefault-lippu ja spots-taulukko (kullakin paikalla on oma id, name ja capacity). Käytä sijaintien ja paikkojen tunnisteita tapahtumia luodessasi.

Kirjaudu Ludoyalla

Sama sivu, jolla API-avaimesi on, tekee organisaatiostasi myös kirjautumispalveluntarjoajan. Anna ihmisten kirjautua omalle sivustollesi, foorumillesi tai yhteisöalustallesi Ludoya-tilillään — ei erillistä salasanaa, jonka he unohtaisivat, eikä käyttäjätietokantaa, jota sinun pitäisi ylläpitää.

Miksi se kannattaa

Kun joku hyväksyy kirjautumisen, hänet liitetään organisaatioosi: ryhmäsi liittymiskäytännöstä riippuen hänestä joko tulee jäsen välittömästi (avoin), hän jättää liittymispyynnön ylläpitäjän hyväksyttäväksi (haku vaaditaan), tai hän vain kirjautuu liittymättä (vain kutsulla). Joka tapauksessa hän näkyy /members-päätepisteessä kuten kuka tahansa — joten sivustosi kirjautuminen ja Ludoya-jäsenlistasi pysyvät automaattisesti tahdissa.

Käyttöönotto

Kyseessä on tavallinen OpenID Connect, joten useimmat alustat tarvitsevat vain issuer-URL:n sekä client ID:n ja salaisuuden. Rekisteröi sovelluksesi Julkisen API:n sivulta saadaksesi nämä tunnukset, ja luettele uudelleenohjaus-URI:t, joita sivustosi käyttää — voit rekisteröidä useita, ja jokaisen on vastattava sivustosi lähettämää redirect_uri-arvoa merkki merkiltä, päättävä kauttaviiva mukaan lukien. Melkein osuma on ylivoimaisesti yleisin syy siihen, että ensimmäinen kirjautumisyritys epäonnistuu.

• Discourse — asenna OpenID Connect -liitännäinen, liitä discovery-URL, lisää tunnukset
• WordPress — mikä tahansa yleinen OpenID Connect -liitännäinen ja sen "auto discover" -valinta
• Kaikki muu — jos se puhuu OIDC:tä, osoita se issuer-URL:iin, niin se määrittää itsensä

Jokainen kirjautuminen palauttaa henkilön pysyvän tunnisteen, käyttäjänimen, näyttönimen ja profiilikuvan sekä sähköpostiosoitteen. Täydet käyttöönotto-ohjeet, myös käsin tehtävä kulku, löytyvät sovelluksen kehittäjäoppaasta kohdasta Developers → Sign in with Ludoya.

Kirjautuville

Kuka tahansa, joka on käyttänyt Ludoyaa kirjautuakseen jonnekin, voi tarkastella näitä yhteyksiä kohdassa Asetukset → Yhdistetyt sovellukset, nähdä milloin kukin liitettiin ja käytettiin viimeksi, ja katkaista minkä tahansa niistä milloin tahansa. Yhteyden katkaiseminen estää sivuston pääsyn välittömästi mutta ei poista häntä ryhmästäsi.

GET /events

Palauttaa tulevat ja menneet tapahtumat erillisinä sivutettuina listoina.

Jokainen tapahtuma sisältää: type (MEETUP tai PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (käyttäjäobjekti tai null), master (käyttäjäobjekti tai null). Käyttäjäobjektit sisältävät id, username, name, avatarUrl.

POST /events

Luo tapahtuman ryhmään. Pakolliset kentät: type ja title. Jos locationId jätetään pois, käytetään ryhmän oletussijaintia; jos sellaista ei ole, palautetaan 400.

Valinnaisia kenttiä ovat: description, locationId, spotId, gameId, parentEventId (alitapahtumille), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Kenttä image hyväksyy joko {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Enintään 5 Mt.

Palauttaa {"id": "string"} tilakoodilla 201.

PUT /events/{eventId}

Päivittää olemassa olevan tapahtuman. Sama rungon rakenne kuin POST-kutsussa — sisällytä vain ne kentät, joita haluat muuttaa. Kutsujan on oltava tapahtuman järjestäjä (ryhmätili). Palauttaa 202 ja tyhjän rungon.

GET /events/{eventId}

Hakee yksittäisen tapahtuman tunnuksen perusteella, samassa muodossa kuin GET /events -listan tietueet.

GET /events/{eventId}/children

Listaa ylätapahtuman sisällä olevat alatapahtumat — suuremman tilaisuuden yksittäiset raidat tai pelisessiot. Jokaisella alatapahtumalla on sama rakenne kuin tavallisella tapahtumalla.

Osallistujien hallinta

Kolme päätepistettä antaa sinun hoitaa tapahtuman osallistujalistaa Ludoyan ulkopuolelta — kätevää, jos ilmoittautumiset tapahtuvat omalla sivustollasi tai jos tuot olemassa olevaa listaa.

GET /members

Palauttaa sivutetun jäsenlistan.

Jokainen jäsen sisältää: id, username, name, avatarUrl, role (OWNER, ADMIN, tai MEMBER).

POST /members/invite

Kutsuu jonkun ryhmääsi. Tämä ottaa vastaan username-arvon suoraan – id:tä ei tarvitse hakea – joten voit lisätä jäseniä suoraan omalta sivustoltasi tai hallintatyökalustasi.

GET /search/users and GET /search/boardgames

Kaksi hakupäätepistettä. Useimmat kirjoitusoperaatiot haluavat nimen sijaan id:n, ja näin sellaisen saa.

GET /search/users

GET /search/boardgames

Lautapelisuodatin ottaa saman puolipistein erotetun key=value-muodon kuin kokoelmasuodatin, joten voit hakea luettelosta pelaajamäärän, peliajan, monimutkaisuuden, vuoden, iän tai tunnisteiden mukaan.

GET /collection

Palauttaa pelikokoelmasi suodatuksineen, lajitteluineen ja sivutuksineen.

Vastaus: totalGames, totalExpansions, games[] — kussakin: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Palauttaa pelitilastot määriteltävissä olevalta aikaväliltä.

Vastaus sisältää:

• Yhteenveto — pelisessiot yhteensä, kokonais- ja keskimääräinen peliaika sekä uniikkien pelien, pelaajien ja sijaintien määrät
• Pelaajittain — henkilökohtaiset pelisessiot, voitot, keskimääräinen ja paras tulos
• Pelaajamäärittäin — erittely 2, 3 ja 4 pelaajan peleihin ja niin edelleen
• Sijainneittain — pelisessioiden määrä ja uniikit pelit paikkaa kohden
• Peleittäin — pelisessioiden määrä, kokonais- ja keskimääräinen peliaika sekä uniikit pelaajat nimikettä kohden

GET /campaigns

Palauttaa sivutetun listan ryhmälle kuuluvista kampanjoista.

Jokainen kampanja sisältää: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Palauttaa ryhmälle kuuluvan kampanjan täydet tiedot.

Vastaus sisältää: Kaikki listakentät sekä template, description, globalNotes, globalState, members[] (kussakin user, role, characterNotes, characterState), sessions[] ja events[].

POST /campaigns

Luo kampanjan ryhmälle. Pakolliset kentät: gameId ja name. Jos näkyvyys jätetään pois, se on oletuksena vain ryhmän jäsenille (ONLY_GROUP).

Valinnaiset kentät: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS tai PRIVATE).

Palauttaa {"id": "string"} tilakoodilla 201.

PUT /campaigns/{campaignId}

Päivittää olemassa olevan kampanjan. Kaikki kentät ovat valinnaisia — sisällytä vain se, mitä haluat muuttaa.

Valinnaiset kentät: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Palauttaa 202 ja tyhjän rungon.

Kampanjan jäsenet

Hallitse sitä, ketkä ovat kampanjassa mukana, samalla tavalla kuin hallitset tapahtuman osallistujia.

Virhekoodit

Aloittaminen

1. Luo API-avain

1. Siirry organisaatiosi profiilisivulle
2. Napauta valikkoa (⋮) → Julkinen API
3. Napauta Luo avain
4. Kopioi avaimesi heti — se näytetään vain kerran eikä sitä voi hakea uudelleen

Avain on sidottu organisaatioosi. Pidä se salassa: kuka tahansa avaimen haltija voi lukea ja kirjoittaa kaikkia yllä mainittuja tietoja.

2. Peruuta tai luo uudelleen

Peruuta olemassa oleva avain palaamalla Julkinen API -sivulle ja napauttamalla Peruuta. Vahvista valintaikkuna. Kaikki vanhaa avainta käyttävät järjestelmät alkavat välittömästi saada 401-virheitä. Anna uusi avain napauttamalla uudelleen Luo avain.

Katso myös:

• Organisaatiot — organisaatiotilit ja Premium-ominaisuudet
• Premium — Business-tason hinnoittelu
• Integraatiot — muut tavat yhdistää Ludoya ulkoisiin työkaluihin