API (aplikacijų programavimo sąsaja) leidžia klientams integruoti TPVS į savo sistemas, įkelti ir gauti duomenis apie įvairius subjektus.
Klientas pateikia HTTP užklausą sistemai, pateikdamas informaciją apie ketinamą veiksmą. HTTP komandos, įprastai naudojamos API:
- GET – šaltinio nuskaitymas;
- POST – šaltinio būsenos keitimas.
Pageidaujamas turinys teikiamas JSON formatu, taikant UFT-8 šifravimą. Jei naudojamas kitas formatas, jis nurodomas metodo aprašyme.
HTTP būsenos kodas nurodo užklausos būseną – jei užklausa sėkminga, rodomas būsenos kodas 200. Su šiuo atsakymu iš serverio bus gauta pageidaujama informacija. Atsakymai skirsis priklausomai nuo API tipo. API atsakymai skirtingiems API tipams aprašyti atitinkamuose skyriuose.
Jei siunčiant užklausą įvyksta klaida, sistema pateiks atsakymą su būsenos kodu. Dažniausi klaidų kodai:
- 400 kodas – bloga užklausa, API užklausa neatpažinta;
- 401 kodas – neįgaliota, tai reiškia, kad įgaliojimo kredencialų nėra arba jie neteisingi;
- 403 kodas – neleidžiama, tai reiškia, kad klientas neturi teisės pasiekti pageidaujamo šaltinio arba atlikti norimo veiksmo;
- 404 kodas – nerasta, tai reiškia, kad pageidautas šaltinis nerastas;
- 500 kodas – vidinė serverio klaida, susisiekite su savo tiekėjo techninės priežiūros skyriumi.
Klaidų kodais pateikiama bendra informacija apie klaidos tipą, todėl vartotojas gali nustatyti jos priežastį.
Kai kurių API atsakymuose yra pasirenkamų elementų (parametrų), juos sistema gali praleisti dėl įvairių priežasčių (nėra duomenų, blogi duomenys, atsakymo laikas baigėsi ir pan.). Negalima manyti, kad tam tikri pasirenkamieji duomenys visuomet bus įtraukti į atsakymą.
API apribojimai
Visų API atveju galioja vienas apribojimas:
- Ne daugiau nei 1 000 užklausų per minutę.
Šis apribojimas galioja visoms TPVS API.
API autentikavimas
API autentikavimas ir įgaliojimas būtinas, norint valdyti API naudojimą skirtingiems klientams ir jų integracijai su skirtingomis sistemomis. Norint pateikti įgaliotą užklausą sistemos API, klientų prašymų programa pirmiausia sistemos vartotojo vardu turi gauti API raktą (API_key).
Klientai gali gauti API raktą tik tiesiogiai susisiekdami su paslaugų teikėjo techninės priežiūros skyriumi. API raktas sudarytas iš atsitiktinių raidžių, skaičių ir simbolių.
Užklausos pavyzdys naudojant API raktą:
Jei API rakto galiojimo laikas pasibaigęs, raktas pašalinamas ar tiesiog išjungiamas, sistema pateiks tokį atsakymą:
API rezultatus, užklausų parametrus ir atsakymus galima peržiūrėti „Swagger“ programoje, naudojantis šia nuoroda: https://api.fm-track.com
Pastaba
Būtina visuomet nurodyti API versiją visų tipų API sąsajose.
Svarbu!
Kadangi API bei sistema, iš kurios gaunama informacija, yra nuolat tobulinamos, vartotojai kartais gali gauti parametrus, kurie nėra pateikti aprašymuose. Rekomenduojama tiesiog ignoruoti nežinomus parametrus, kurie nėra pateikti API aprašymuose.
Versijavimas ir suderinamumas
Aplikacijų programavimo sąsajos (toliau – API) sprendimas yra pastoviai atnaujinamas, tobulinamas bei keičiamas. Dėl to reikia žinoti, ką reiškia suderinamumo terminas, kalbant apie API, ir kokią įtaką jis daro vartotojui, besinaudojančiam API sprendimu.
Atnaujinus API yra galimi du scenarijai:
- API atgalinis suderinamumas yra užtikrintas – tai reiškia, jog atlikti pakeitimai neturės jokios įtakos API darbo eigai, tad nauja API versija nekuriama;
- API atgalinis suderinamumas neužtikrintas – tai reiškia, jog kai kurie API komponentai po pakeitimų veikia nebe taip pat, kaip anksčiau. Tokiu atveju išleidžiama nauja API versija.
API atgalinis suderinamumas yra užtikrintas, kuomet:
- Pridedamas naujas API resursas;
- Prie esamos API pridedami nauji papildomi užklausos parametrai;
- Prie esamų API atsakymų pridedami nauji parametrai;
- Pakeičiama parametrų tvarka esamuose API atsakymuose;
- Pakeičiamas objektų ID ar kitų nepermatomų teksto eilučių ilgis arba formatas; Vartotojas gali daryti prielaidą, kad sistemos generuojami objektų ID niekada nebus ilgesni nei 255 ženklai, tačiau 255 ženklų ID taip pat turėtų būti apdorojami. Pavyzdžiui, jei vartotojas naudoja MySQL, objektų ID turėtų būti laikomi VARCHAR(255) COLLATE uft8_bin tipo stulpelyje (COLLATE konfigūracija užtikrina, kad paieškos metu būtų skiriamos didžiosios ir mažosios raidės);
- Pridedami nauji ENUM tipo kintamieji – bet kuri sistema turėtų be keblumų susitvarkyti su neatpažintais ENUM tipo kintamaisiais. Pavyzdžiui, kintamojo reikšmių rinkinio pasikeitimas iš [Privatus, Verslo] į [Privatus, Darbo, Verslo] sistemai neturėtų turėti jokios įtakos.