17. Integraatio-API ja API-avaimet

Integraatiorajapinnan (API) avulla oma ohjelmasi, taulukkosi tai skriptisi voi lukea projektiesi tiedot koneellisesti: projektiluettelon, kaapeli- ja materiaaliluettelot, jakokeskusten piiritaulukon ja riviliitinluettelon, määräluettelon sekä piirustuspaketin kokoonpanon. Rajapinta on vain luku: se ei muuta piirustusta eikä projektia.

Kuka voi saada API-avaimen

Ylläpitäjä sallii API-avaimen tilikohtaisesti. Jos tilillesi on annettu oikeus, Profiili-sivulla näkyy API-avaimet-kortti; ilman oikeutta korttia ei näy. Tilillä voi olla yhtä aikaa enintään 5 aktiivista avainta.

Avain näkee samat projektit kuin sinä: omasi ja pyynnöstä ne, jotka on jaettu sinulle. Jaetun projektin luettelot ja määräluettelo luovutetaan vain, jos jako sallii myös viennin.

Avaimen luominen

1. Napsauta Profiili-sivun API-avaimet-kortissa Uusi avain -painiketta.
2. Anna avaimelle nimi (esimerkiksi sen ohjelman nimi, joka sitä käyttää).
3. Valitse käyttöalue: Projektien luku antaa projektiluettelon ja projektien tiedot, Dokumenttien luku antaa luettelot, määräluettelon ja piirustuspaketin. Valitse vain se, mitä ohjelma todella tarvitsee.
4. Valitse voimassaoloaika: 30, 90 tai 365 päivää. Vanhentunut avain ei enää toimi; luot tilalle uuden.
5. Anna nykyinen salasanasi (salasanattomalla tilillä tarvitaan tuore kirjautuminen). Ensimmäisen avaimen kohdalla hyväksy API:n käyttöehdot.

Luomisen jälkeen avain näkyy vain kerran: kopioi se ja tallenna turvalliseen paikkaan. Myöhemmin luettelossa näkyy vain sen etuliite (avk_…), luomis- ja vanhenemispäivä, viimeisin käyttö ja kutsujen määrä. Uudesta avaimesta lähetetään myös sähköposti-ilmoitus (ilman itse avainta).

Avaimen mitätöinti

Kortilla avaimen vieressä olevalla Mitätöi-painikkeella avain muuttuu heti käyttökelvottomaksi; tätä ei voi peruuttaa. Mitätöi avain, kun et enää käytä sitä, kun lopetat sitä käyttäneen ohjelman tai kun epäilet sen vuotaneen.

Turvallisuusvinkit

• Käsittele avainta kuten salasanaasi: jokainen, joka sen tuntee, voi lukea projektejasi annetun käyttöalueen puitteissa.
• Säilytä se salaisuuksien säilössä (salasanahallinta, palvelimen ympäristömuuttuja tai CI:n salainen muuttuja), ei lähdekoodissa: älä vie sitä git-repositorioon, jaettuun taulukkoon tai sähköpostiin.
• Älä käytä sitä selaimessa ajettavassa koodissa (verkkosivu, selaimen laajennus): siellä kuka tahansa voi lukea sen. Avaimen paikka on palvelimella, skriptissä tai työpöytäohjelmassa.
• Anna jokaiselle ohjelmalle oma avain mahdollisimman suppealla käyttöalueella ja lyhyellä voimassaololla; näin yhden avaimen mitätöinti ei pysäytä muita.

Käyttö ohjelmasta

Avain lähetetään pyynnön otsakkeessa Bearer-tunnisteena: Authorization: Bearer avk_…. Päätepisteet ovat polun /api/v1/ alla (esimerkiksi GET /api/v1/projects), ja vastaus on JSON. Tarkka kuvaus OpenAPI-muodossa on osoitteessa /api/v1/openapi.json; useimmat kehitystyökalut osaavat tuoda sen.

Kutsujen määrä on rajoitettu avainta ja tiliä kohden (oletuksena 60 minuutissa ja 10 000 päivässä); rajan ylittyessä palvelin vastaa 429, odota silloin hetki. Verkkokirjautuminen (eväste) ei avaa rajapintaa, eikä avain kirjaa sinua sisään verkkokäyttöliittymään.