API-määrittely

Täydellinen REST-päätepisteviittaus. Tutoriaaleja ja esimerkkejä varten katso API-opas.

Kaikki minkä projektin jäsen voi tehdä verkkokäyttöliittymässä on saatavilla täällä — SPA käyttää tätä samaa APIa. Operaatiot, jotka vaativat omistajan roolin, on merkitty (owner); kaikki muu vaatii vain projektin jäsenyyttä (tai, lukuoperaatioille jotka on merkitty (viewer), minkä tahansa käyttöoikeustason).

Perusta

https://eastagiletracker.com/api/v1

https://api.eastagiletracker.com/api/v1 tarjoaa identtisen APIn. Kaikki pyynnöt ja vastaukset ovat JSON-muotoa, lukuun ottamatta muutamia tiedostonlatauspäätepisteitä, jotka hyväksyvät multipartin.

Tunnistautuminen

Jokainen tunnistautunut pyyntö lähettää API-avaimen yhdellä seuraavista:

• X-TrackerToken: <key>
• Authorization: Bearer <key>

Käyttäjäavaimet alkavat ea_user_. Agenttiavaimet alkavat ea_agent_. Katso API-opas → Kaksi avaintyyppiä.

Tunnistautumattomat päätepisteet: /openapi.json, /docs, /auth/*-päätepisteet ja viitedatahaut (/story_types, /story_states, /effort_scales, …). /meta on tunnistautunut — mikä tahansa kelvollinen avain toimii, mutta se ei ole projektirajattu (projektiin sidottu agenttiavain tavoittaa sen myös).

Roolit

Kolme tasoa portittaa projektirajattuja päätepisteitä:

Taso	Kuka pääsee	Tyypilliset operaatiot
viewer	viewer, member, owner	luvut (listaa/hae tarinoita, haku, analytiikka)
member	member, owner	kaikki työkohteiden kirjoitukset (tarinat, tehtävät, kommentit, …)
owner	vain owner	projektin asetukset, jäsenyyden hallinta, agenttiavaimet, poisto, tuonti, auditointiloki

Ei-jäsen saa 404 unfound_resource (ei 403) projektipoluilla, joten projektien ID:t eivät ole lueteltavissa.

Itseään kuvaavat päätepisteet

Metodi	Polku	Kuvaus
GET	/openapi.json	Live OpenAPI 3 -spesifikaatio. Tunnistautumaton.
GET	/docs	Swagger UI. Tunnistautumaton.
GET	/meta	Kutsujan identiteetti (auth.kind/key_id/agent_id/project_id) + tarinatyypin siirtymägraafi. Tunnistautunut (mikä tahansa kelvollinen avain; ei projektirajattu). Kutsu tätä ensin.

Tili / identiteetti

Nämä vaikuttavat kutsujaan ja tarvitsevat vain kelvollisen avaimen (ei projektiroolia).

Metodi	Polku	Kuvaus
POST	/auth/register	Rekisteröi uusi tili
POST	/auth/login	Kirjaudu sisään, palauttaa istuntotunnuksen
POST	/auth/logout	Kirjaudu ulos
POST	/auth/forgot-password	Pyydä salasanan palautussähköposti
POST	/auth/reset-password	Käytä palautustunnusta uuden salasanan asettamiseen
GET	/auth/verify-email	Vahvista sähköpostiosoite
POST	/auth/accept-invite/lookup	Selvitä kutsutunnus → sähköposti (tunnistautumaton)
POST	/auth/accept-invite	Hyväksy projektikutsu (tunnistautumisen jälkeen)
GET	/me	Nykyisen käyttäjän profiili
PUT	/me	Päivitä profiili
DELETE	/me	Poista tili
PUT	/me/password	Vaihda salasana
PUT	/me/settings	Päivitä asetukset (teema, ilmoitusasetukset)
POST	/me/avatar	Lataa avatar (multipart)
POST	/me/api-token/regenerate	Kierrätä API-tunnuksesi — mitätöi olemassa olevat istunnot/avaimet
GET	/me/api_keys · POST /me/api_keys · DELETE /me/api_keys/{id}	Hallitse käyttäjän (ea_user_) API-avaimia
GET	/me/activity	Toimintasi kaikkien projektien yli
GET	/me/data-export	GDPR-itsevienti tiedoistasi
GET	/me/consent · POST /me/consent	Lue / tallenna suostumus ({ consent_type, granted })
GET	/legal/pending · POST /legal/accept	Odottavat clickwrap-asiakirjat / tallenna hyväksyntä
POST	/contact · POST /feedback · POST /feedback/with-screenshot	Yhteydenotto + sovelluksen sisäinen palaute

Viitedata (tunnistautumaton)

Siemenhaut, joita käytetään tarinoita luotaessa/arvioitaessa. Vakaat ID:t.

Metodi	Polku	Kuvaus
GET	/story_types	feature, bug, chore, release (+ allow_points)
GET	/story_states	unstarted … accepted, rejected
GET	/effort_scales	käytettävissä olevat arviointiasteikot
GET	/effort_scales/{scale_id}/values	asteikon pistearvot

Projektit

Metodi	Polku	Kuvaus
GET	/projects	Listaa projektisi
POST	/projects	Luo projekti
GET	/projects/{id}	Hae projektin tiedot (viewer)
PUT	/projects/{id}	Päivitä projektin asetukset (owner)
DELETE	/projects/{id}	Poista projekti (owner)
GET	/projects/{id}/audit-log	Projektin toimintavirta (owner)
GET	/projects/{id}/events	Kursorisivutettu tapahtumavirta (viewer) — katso Tapahtumat

Jäsenet ja agenttiavaimet

Metodi	Polku	Kuvaus
GET	/projects/{id}/memberships	Listaa jäsenet (viewer)
POST	/projects/{id}/memberships	Kutsu jäsen sähköpostitse (owner)
PUT	/projects/{id}/memberships/{mid}	Päivitä rooli (owner)
DELETE	/projects/{id}/memberships/{mid}	Poista jäsen (owner)
GET / POST	/projects/{id}/agent_keys	Listaa / luo agenttiavaimia (owner)
DELETE	/projects/{id}/agent_keys/{kid}	Peruuta agenttiavain (owner)

Tarinat

Kaikki tarinakirjoitukset vaativat member-roolin.

Metodi	Polku	Kuvaus
GET	/projects/{id}/stories	Listaa tarinat (sivutettu, suodatettavissa) (viewer)
POST	/projects/{id}/stories	Luo tarina
GET	/projects/{id}/stories/{sid}	Hae yksi tarina (viewer)
PUT	/projects/{id}/stories/{sid}	Päivitä tarina
DELETE	/projects/{id}/stories/{sid}	Poista tarina
POST	/projects/{id}/stories/{sid}/transitions	Vaihda tilaa validoinnilla
POST	/projects/{id}/stories/bulk_transition	Siirrä useita tarinoita (1–100) kerralla
POST	/projects/{id}/stories/bulk-delete	Poista useita tarinoita
POST	/projects/{id}/stories/bulk-duplicate	Monista useita tarinoita
POST	/projects/{id}/stories/{sid}/duplicate	Monista yksi tarina

Luo (POST …/stories): { "name" (required), "story_type": "feature|bug|chore|release", "description"?, "estimate"?, "current_state"?, "icebox"?, "labels"? }. labels hyväksyy ["auth"] tai [{ "name": "auth" }]; tuntemattomat tunnisteet luodaan. Oletukset: story_type=feature, current_state=unstarted.

Päivitä (PUT …/stories/{sid}): samat kentät, kaikki valinnaisia, lisäksi "position" (float) ja "force_state_change" (bool).

Siirtymä (POST …/transitions): { "to": "<state>", "reason"? }. Kenttä on to. Palauttaa { story_id, state }. Laiton siirto → 422 invalid_transition, jossa details: { from, to, allowed }.

Massasiirtymä (POST …/bulk_transition): { "story_ids": [int,…] (1–100), "to": "<state>", "reason"? }. Jokainen tarina arvioidaan itsenäisesti; palauttaa { results: [ { id, status: "ok" } | { id, status: "failed", error } ] }.

Tarinan aliresurssit

Kaikki member. Useimpien listaus/GET on (viewer).

Metodi	Polku	Runko / huomiot
GET / POST	/projects/{id}/stories/{sid}/tasks · PUT/DELETE …/tasks/{tid}	{ description (or task_desc), complete?, task_order? }
GET / POST	/projects/{id}/stories/{sid}/comments · PUT/DELETE …/comments/{cid}	{ text (or comment_text) } or { comment_emoji }
GET / POST	/projects/{id}/stories/{sid}/blockers · PUT/DELETE …/blockers/{bid}	{ blocker_desc, resolved? }
GET / POST	/projects/{id}/stories/{sid}/links · DELETE …/links/{lid}	{ url, link_type?, title? }
GET / POST	/projects/{id}/stories/{sid}/reviews · PUT/DELETE …/reviews/{rid}	{ reviewer_id? / reviewer_agent_id?, status, comment? }
GET / POST	/projects/{id}/stories/{sid}/owners · DELETE …/owners/{mid} · DELETE …/owners/agents/{aid}	{ member_id? / agent_id? } — jätä molemmat pois lisätäksesi kutsujan
GET / POST	/projects/{id}/stories/{sid}/followers · DELETE …/followers/{mid} · DELETE …/followers/agents/{aid}	{ member_id? / agent_id? }
GET / POST	/projects/{id}/stories/{sid}/labels · DELETE …/labels/{lid}	{ name }
GET / POST	/projects/{id}/stories/{sid}/attachments (+ /json) · DELETE …/attachments/{aid}	multipart-lataus (≤ 2 GB kukin); listaus on (viewer)

Tunnisteet

member kirjoituksille, (viewer) luvuille.

Metodi	Polku	Kuvaus
GET / POST	/projects/{id}/labels	Listaa / luo tunniste
PUT / DELETE	/projects/{id}/labels/{lid}	Päivitä / poista tunniste
POST	/projects/{id}/labels/{lid}/archive	Arkistoi (piilota pehmeästi) tunniste

Iteraatiot

Metodi	Polku	Kuvaus
GET	/projects/{id}/iterations	Listaa iteraatiot (member)
POST	/projects/{id}/iterations	Luo manuaalinen iteraatio (owner)
DELETE	/projects/{id}/iterations/{itid}	Poista iteraatio (owner)

Haku, analytiikka, mittarit, asetukset

Metodi	Polku	Kuvaus
GET	/projects/{id}/search?query=…	Suodatinsyntaksihaku (viewer) — katso opas
GET	/projects/{id}/analytics/{overview,iteration,releases,activity,cycle-time,projections}	Analytiikka (viewer). Iteraation poraus ottaa ?iteration_id=
GET	/projects/{id}/metrics/{velocity,burndown,story-types}	Mittarit (viewer)
GET / PUT	/projects/{id}/preferences	Lautasi asetukset tälle projektille (member)

Tapahtumat

Metodi	Polku	Kuvaus
GET	/projects/{id}/events	Kursorisivutettu tapahtumavirta (viewer)

Kyselyparametrit: since=<event_id>, types=story.created,story.transitioned,comment.created,…, limit=, cursor=. Vastaus sisältää next_cursor. Välitä viimeisin näkemäsi event_id arvona since jatkaaksesi.

Tuonti (owner)

Metodi	Polku	Kuvaus
POST	/projects/{id}/import (+ /json)	Multipart-lataus. source= ∈ pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

WebSocket

wss://eastagiletracker.com/ws/control?token=<key>

Interaktiiviseen käyttöliittymän etäohjaukseen ({ "action": "get_state", "id": "req-1" }). Ei datakanava — kaikki luvut/kirjoitukset kulkevat RESTin kautta. Vain yksi instanssi; ei jaeta replikoiden kesken.

Idempotenssi

Kirjoituspäätepisteet (POST, PUT, DELETE) hyväksyvät Idempotency-Key-otsakkeen. Sama avain + sama runko toistaa välimuistitetun vastauksen (24 tunnin ikkuna); sama avain + eri runko palauttaa 409 idempotency_conflict. Ei sovelleta metodeihin GET/HEAD/OPTIONS, polkuihin /auth/* tai /attachments. 5xx-vastauksia ei koskaan välimuistiteta — uudelleenyritys tavoittaa käsittelijän.

Sivutus

Listapäätepisteet hyväksyvät cursor=<opaque> ja limit=<n≤200>. Kun asetettu, vastaus on { "items": [...], "next_cursor": "<str|null>" }; välitä next_cursor takaisin sivuttaaksesi. Jotkin listat palauttavat myös X-Tracker-Pagination-Total-otsakkeen.

Kenttäprojektio

Listapäätepisteet hyväksyvät fields= (pilkuin erotettu) palauttaakseen vain tietyt kentät. story_id sisältyy aina; tuntematon kentän nimi palauttaa 400 validation_failed, jossa virheelliset nimet ovat kohdassa details.fields.

GET /projects/123/stories?fields=story_id,name,current_state,owners

Virhemuoto

Jokaisella JSON-virheellä on code ja error; jotkin lisäävät details:

{ "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] } }

Status	code	Milloin
400	invalid_parameter	virheellinen syöte; viesti kohdassa error, ei details (useimmat validoinnit: tyhjä/pituus/null-tavu/sähköposti)
400	validation_failed	jäsennelty syötevirhe; details.fields on taulukko virheellisten kenttien nimistä
401	unauthenticated	puuttuva/virheellinen tunnus
403	unauthorized_operation	tunnistautunut mutta riittämätön rooli
404	unfound_resource	ei löytynyt — palautetaan myös ei-jäsenille
409	conflict	resurssikonflikti (esim. duplikaatti)
409	idempotency_conflict	Idempotency-Key uudelleenkäytetty eri rungolla
422	invalid_transition	laiton tilasiirto; details kantaa { from, to, allowed }
500	internal_error	palvelinvika — yleinen viesti; turvallista yrittää uudelleen

details.fields on JSON-taulukko kenttien nimistä (esim. ["to"]), joskus lisäavaimin kuten max. Kenttä→viesti-karttaa ei ole.

{ "code": "validation_failed", "error": "unknown field(s): foo", "details": { "fields": ["foo"] } }

Nopeusrajat

Avainkohtainen (IP-kohtainen tunnistautumattomille päätepisteille), GCRA-token bucket:

• Auth — /auth/*: 0,5 pyyntöä/s, purske 20.
• Julkinen — /contact, /feedback: 0,2 pyyntöä/s, purske 10.
• Arkaluonteinen — salasanan palautus: ~0,002 pyyntöä/s, purske 5.

Ylitetty raja palauttaa 429 Too Many Requests, jossa on Retry-After-otsake ja pelkkätekstinen runko (ei JSON-virhekuori).