17. Integratsiooni API ja API-võtmed

Integratsiooni-API võimaldab sinu enda programmil, tabelil või skriptil sinu projektiandmeid masinaga lugeda: projektide loendit, kaabli- ja materjaliloendeid, jaotuskilpide vooluringide tabelit ja klemmiloendit, koguste väljavõtet ning projektikomplekti koostamist. API ainult loeb: joonist ja projekti ta ei muuda.

Kes saab API võtme

API-juurdepääsu lubab operaator kontopõhiselt. Kui sinu konto on loa saanud, ilmub lehele Profiil kaart API võtmed; ilma loata on kaart peidetud. Ühel kontol võib korraga olla kuni 5 aktiivset võtit.

Võti näeb samu projekte, mida sina: sinu enda omi ja soovi korral neid, mida sinuga on jagatud. Jagatud projekti loendeid ja koguste väljavõtet antakse välja ainult siis, kui jagamine lubab ka eksportimist.

Võtme loomine

1. Lehe Profiil kaardil API võtmed klõpsa nuppu Uus võti.
2. Anna võtmele nimi (näiteks selle programmi nimi, mis seda kasutab).
3. Vali ulatus: Projektide lugemine annab projektide loendi ja projektide andmed, Dokumentide lugemine annab loendid, koguste väljavõtte ja projektikomplekti. Vali ainult see, mida programm tõesti vajab.
4. Vali aegumine: 30, 90 või 365 päeva. Aegunud võti lakkab töötamast; loo selle asemel uus.
5. Sisesta oma praegune parool (paroolita konto vajab värsket sisselogimist). Esimese võtme puhul nõustu API kasutustingimustega.

Pärast loomist näidatakse võtit ainult ühe korra: kopeeri see ja hoia turvalises kohas. Hiljem näitab loend ainult selle eesliidet (avk_…) koos loomise ja aegumise kuupäeva, viimase kasutuse ning kutsete arvuga. Uue võtme kohta saadame ka e-posti teate (ilma võtmeta).

Võtme tühistamine

Kaardil võtme kõrval olev nupp Tühista muudab võtme koheselt kasutuskõlbmatuks; seda ei saa tagasi võtta. Tühista võti, kui sa seda enam ei kasuta, kui lõpetad programmi, mis seda kasutas, või kui kahtlustad, et see on lekkinud.

Turvanõuanded

• Käsitle võtit nagu oma parooli: igaüks, kes seda teab, saab lugeda sinu projekte antud ulatuses.
• Hoia seda saladuste hoidlas (paroolihaldur, serveri keskkonnamuutuja või CI salajane muutuja), mitte lähtekoodis: ära pane seda git-hoidlasse, jagatud tabelisse ega e-kirja.
• Ära kasuta seda brauseris töötavas koodis (veebileht, brauserilaiend): seal saab igaüks seda lugeda. Võtme koht on serveris, skriptis või töölauaprogrammis.
• Anna igale programmile oma võti võimalikult kitsa ulatuse ja lühikese aegumisega; nii ei peata ühe võtme tühistamine midagi muud.

Kasutamine programmist

Võti saadetakse päringu päises Bearer-tokenina: Authorization: Bearer avk_…. Lõpp-punktid asuvad aadressi /api/v1/ all (näiteks GET /api/v1/projects) ja vastus on JSON. Täielik kirjeldus OpenAPI vormingus on saadaval aadressil /api/v1/openapi.json; enamik arendustööriistu oskab seda importida.

Kutsete arv on piiratud võtme ja konto kohta (vaikimisi 60 minutis ja 10 000 päevas); ületamisel vastab server koodiga 429, seega oota veidi. Veebilehele sisselogimine (küpsis) API-t ei ava ja võti ei logi sind veebiliidesesse sisse.