Skip to content

api.md

Latest commit

 

History

History
91 lines (76 loc) · 6.52 KB

api.md

File metadata and controls

91 lines (76 loc) · 6.52 KB
Raw

API

REST API pod /api. Točan opis svih zahtjeva i odgovora je OpenAPI dokument na /openapi/v1.json (u okruženju Development); iz njega se generiraju i TypeScript tipovi frontenda. Primjeri zahtjeva su u Terminus.WebApi.http.

Prijava

Sve osim /api/public/*, /api/auth/login i /health traži prijavu (inače 401).

  • Prijava: POST /api/auth/login s e-mailom i lozinkom postavlja kolačić terminus_auth (HttpOnly, SameSite=Strict, u produkciji samo preko HTTPS-a). Vrijedi 14 dana i produljuje se korištenjem.
  • Nakon 5 neuspjelih pokušaja račun je zaključan 15 minuta (429).
  • Ključevi za kolačiće čuvaju se u bazi, pa prijava preživi restart i deploy.
  • Promjena lozinke (PUT /api/auth/password) odjavljuje ostale preglednike (najkasnije za 5 minuta).
  • Prvi administrator dolazi iz konfiguracije (vidi lokalni razvoj).

Endpointi za administratora

Resurs Endpointi
Prijava POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me, PUT /api/auth/password
Prvo pokretanje GET /api/setup, POST /api/setup/blank
Postavke instance GET/PUT /api/settings, PUT/DELETE /api/settings/logo
Prijevoznici /api/agencies; DELETE /api/agencies/{id}?moveRoutesTo= linije i cijene prvo prebacuje na drugog prijevoznika
Stanice /api/stops, /api/stops/area, /api/stops/extent
Tablica stanica GET /api/stops/table – filtri popisa i wheelchairBoarding, hasTrips, hasCoordinates, routeId; redoslijed sortBy (Name, Code, PublicCode, PlatformCode, LocationType, WheelchairBoarding, IsActive, RouteCount, UpdatedAt) i sortDescending; uz svaku stanicu kolodvor, broj perona i linije
Stanice: grupna izmjena POST /api/stops/bulk/active { ids, isActive } – najviše 500; pravila kao kod jedne stanice, a ako ijedna ne smije, ne mijenja se nijedna; vraća { changed }
Stanica: linije i polasci /api/stops/{id}/routes, /api/stops/{id}/departures?date=
Stanica: PDF vozni red GET /api/stops/{id}/timetable.pdf?from=&to=&paper=&language=
Stanice: PDF POST /api/stops/pdf { ids, timetable, routes, from, to, paper, language, showMinutes, minutesFromStop } – do 100 stanica u jednom PDF-u; za svaku vozni red, sheme linija sa stanice ili oboje, svaki od nove stranice; stanice bez ičega za ispis se preskaču (broj u zaglavlju X-Skipped-Stops), 422 ako ih nema nijedna
Linija: PDF shema GET /api/routes/{id}/diagram.pdf?paper=&language=&showMinutes=
Stanica: PDF shema svih linija GET /api/stops/{id}/routes.pdf?paper=&language=&showMinutes=&minutesFromStop=
Linije /api/routes, /api/routes/{id}/patterns, /api/routes/{id}/timetable?date=&directionId=
Tablica linija GET /api/routes/table – filtri popisa i hasTrips, stopId; redoslijed sortBy (Default, Code, ShortName, LongName, RouteType, Agency, IsActive, VariantCount, ValidTo, UpdatedAt) i sortDescending; uz svaku liniju prijevoznik, broj varijanti i razdoblje voznog reda (validFrom–validTo: najraniji početak i najkasniji kraj kalendara njezinih vožnji)
Linije: grupna izmjena POST /api/routes/bulk/active { ids, isActive }, POST /api/routes/bulk/agency { ids, agencyId } (vožnje i vozni red ostaju) – najviše 500; vraća { changed }
Linija: karta uživo (vožnje dana) GET /api/routes/{id}/live?date=
Karta uživo: sva vozila GET /api/routes/live?date=
Javna karta (bez prijave, ako je uključena) /api/public/map/stops/area, /stops/extent, /stops/{id}/departures?date=, /stops/{id}/routes, /routes/{id}/live?date=, /live?date=
Varijante linija /api/routes/{id}/variants, POST /api/routes/{id}/variants/derive (iz vožnji), /api/variants/{id}
Linija: grafikon voznog reda GET/PUT /api/routes/{id}/schedule?directionId=&calendarId= (vožnje s vremenima u sekundama; spremanje izmjena u jednoj transakciji, 409 kod sukoba; dayTypes vožnje su svi tipovi dana njezina polaska, a detach je izdvaja iz polaska)
Kalendari i iznimke /api/calendars, /api/calendars/overview?date=, /api/calendars/{id}/dates
Sezone voznog reda /api/seasons, POST /api/seasons/{id}/copy (kopija za drugo razdoblje, po želji s vožnjama), DELETE /api/seasons/{id}?withTrips=true (briše i vožnje sezone), PUT /api/seasons/{id}/day-types, PUT /api/seasons/{id}/periods (razdoblja, npr. školski raspusti), PUT/DELETE /api/seasons/{id}/days/{date}, GET /api/seasons/holiday-countries
Vožnje i vremena /api/trips, /api/trips/{id}/stop-times
Trase /api/shapes
Cijene karata /api/fares
Izdavač feeda /api/feed-info
GTFS uvoz (zamjenjuje sve podatke) POST /api/gtfs/import/preview, POST /api/gtfs/import (polja variants, skipExpired i createSeason)
GTFS izvoz GET /api/gtfs; provjere bez izvoza GET /api/gtfs/check ({ problems }, prazno ako je feed spreman)

Resursi bez navedene metode imaju uobičajeni CRUD: GET popis (straničen, page i pageSize ≤ 100), GET /{id}, POST, PUT /{id} (zamjenjuje cijeli resurs) i DELETE /{id}.

Detalji pojedinih područja:

Javni endpointi (bez prijave)

Resurs Endpoint
Sljedeći polasci sa stanice GET /api/public/departures/{stopCode}?limit=10&past=0
Naziv, boje i logo instance GET /api/public/settings, GET /api/public/settings/logo
GTFS feed (ako je objavljen u postavkama) GET /api/public/gtfs
Stanje aplikacije i baze GET /health

Javne endpointe stalno dohvaćaju zasloni na stanicama, pa imaju cache na poslužitelju i ograničenje broja zahtjeva po IP adresi (iznad granice 429 s Retry-After). Vrijednosti su u departures-and-timetables.md.

Greške

Greške se vraćaju kao ProblemDetails:

Status Kada Dodatno
400 neispravni podaci errors: greške po polju
401 nije prijavljen
404 resurs ne postoji
409 sukob s postojećim podacima (npr. duplikat koda)
422 podaci nisu spremni za operaciju (GTFS izvoz, polasci, PDF) problems: popis što treba ispraviti
429 previše zahtjeva ili zaključan račun Retry-After kod javnih endpointa