Webb-API
Webb-API:t är ett litet läs-API i JSON över HTTP som en framtida hemsida kan hämta serverdata från: status, samhällen, företag, topplistor, stadskarta, marknad och enskilda spelare. Det är enbart läsande och rör aldrig spelardata eller ekonomi. Just nu är det AVSTÄNGT (webb.aktiv: false) tills hemsidan byggs. Alla ändpunkter med exempelsvar och en färdig nginx-uppsättning finns i docs/WEBB-API.md.
Slå på webb-API:t
Två saker: aktivera det i config.yml och ladda om. Lyssnaren binder som standard till 127.0.0.1:4021 och är alltså inte nåbar utifrån förrän nginx står framför.
Aktivera i config.yml
Sätt webb.aktiv: true i plugins/NordGuild/config.yml. Vill du ha lösenordsskydd sätter du också webb.token – då krävs headern Authorization: Bearer <token> på varje anrop. Är nginx på samma maskin enda klienten räcker det att lyssnaren binder till 127.0.0.1, och då kan token lämnas tom.
Ladda om pluginet
Reload startar också om API:t med de nya inställningarna.
/nordguild reloadKontrollera
Visar adressen, om token krävs, om lyssnaren bara är lokal, hastighetsgränsen, cachetiden, topplistestorleken, om rikaste visas, samt trafiken: antal förfrågningar, avvisade, fel och senaste felet.
/webb statusSätt nginx framför
Följ nginx-exemplet i docs/WEBB-API.md. På VPS:en finns mallen /etc/nginx/sites-available/nordguild.example, ännu inte aktiverad. Portarna 4020 (hemsidan) och 4021 (API:t) är reserverade.
Kommandon
Samma som /webb status.
Adress (http://bind:port/api/), om token krävs, om lyssnaren bara är lokal, hastighetsgräns, cachetid, topplistestorlek, om rikaste spelare visas, samt trafik: antal förfrågningar, avvisade med 429, fel och det senaste felet.
Startar lyssnaren. Kräver webb.aktiv: true i config.yml.
Stoppar lyssnaren. Porten släpps direkt.
Stoppar och startar igen. Används efter att du ändrat webb:-sektionen och kört /nordguild reload.
Inställningar under webb: i config.yml
| Nyckel | Vad den styr | Standard |
|---|---|---|
| aktiv | Om API:t startas alls. Just nu false. | false |
| bind | Adressen lyssnaren binder till. 127.0.0.1 betyder att bara maskinen själv, till exempel nginx, når den. | 127.0.0.1 |
| port | Porten. | 4021 |
| token | Valfri delad hemlighet. Är den satt krävs headern Authorization: Bearer <token> på varje anrop. Lämna tom när nginx på samma maskin är enda klienten. | tom |
| visa_rikaste | Visa topplistan rikaste spelare (namn och saldo) i /api/topplistor. | true |
| max_forfragningar_per_sekund | Total hastighetsgräns för hela API:t, samma burst. Överskott får svaret 429. | 30 |
| cache_sekunder | Sätter Cache-Control: public, max-age på alla svar så hemsidan och nginx kan cacha. | 15 |
| topplista_antal | Antal poster i varje topplista. | 10 |
| tidsgrans_sekunder | Tak för hur länge en enskild förfrågan får arbeta innan den svarar 503. | 5 |
Ändpunkter
| Ändpunkt | Vad den ger |
|---|---|
| GET /api/status | Servernamn, version, online av max, antal samhällen, företag och butiker samt penningmängden. |
| GET /api/samhallen | Alla aktiva samhällen. |
| GET /api/samhallen/{id} | Ett samhälle med medlemmar, tomter och företag. {id} är UUID. |
| GET /api/samhallen/{id}/karta | Stadens tomt- och byggnadskarta som rutnät. |
| GET /api/foretag | Alla levande företag. |
| GET /api/foretag/{id} | Ett företag med anställda, butiker och recensioner. {id} är UUID, kontonummer som SE-000012, eller bara numret. |
| GET /api/topplistor | Rikaste spelare, största företag, högsta yrkesnivåer och största samhällen. |
| GET /api/marknad | Vad Centrala marknaden köper med aktuellt pris, plus marknadsvärden. |
| GET /api/spelare/{namn} | Offentlig spelarprofil. Namnet är skiftlägesokänsligt och URL-kodat. |
Felkoder
| Kod | När |
|---|---|
| 401 | webb.token är satt men headern Authorization: Bearer <token> saknas eller är fel. |
| 404 | Okänd sökväg, eller resursen finns inte: okänt id eller namn, upplöst samhälle, avregistrerat företag. |
| 405 | Annan metod än GET eller OPTIONS. |
| 429 | Hastighetsgränsen nådd. Svaret har Retry-After: 1. |
| 500 | Internt fel. Loggas i konsolen. |
| 503 | Förfrågan överskred tidsgrans_sekunder. |
Bra att veta
API:t är avstängt tills hemsidan byggs
webb.aktiv står på false i plugins/NordGuild/config.yml. Ingen port öppnas och ingen data lämnar servern förrän du sätter det till true, kör /nordguild reload och eventuellt /webb starta.
Varning: Lyssnaren ska inte nås utifrån
Håll bind på 127.0.0.1 och låt nginx stå framför. Ska något annat än nginx på samma maskin nå API:t sätter du webb.token och kräver Bearer-token på varje anrop.
Så ser svaren ut
Allt är application/json med utf-8. Pengar levereras både som heltal öre i <nyckel>_ore och som färdig svensk sträng i <nyckel> – räkna alltid på _ore. Tider kommer som ISO-8601 i UTC plus ett svenskt datum i <nyckel>_datum. Nycklarna är svenska utan diakritiska tecken, till exempel samhalle, niva och foretag. Svaren sätter Cache-Control enligt cache_sekunder (felsvar no-store), tillåter CORS från alla ursprung för GET och OPTIONS, och skickar X-Content-Type-Options: nosniff.
/api svarar som /api/status
Avslutande snedstreck spelar ingen roll.
Start och stopp revisionsloggas
Både /webb starta och /webb stoppa hamnar i revisionsloggen under kategorin ADMIN. /nordguild reload startar också om API:t med de nya inställningarna.