API (sučelje za programiranje aplikacija) omogućuje klijentima integraciju FMS-a sa svojim sustavima, povlačenje i slanje podataka o različitim entitetima.
Klijent šalje HTTP zahtjeve sustavu, pružajući informacije o namjeravanoj radnji. HTTP naredbe koje se obično koriste u API-ju:
- GET – Pročitaj resurs;
- POST – Promjena stanja resursa;
Traženi sadržaj se pruža u JSON formatu s UTF-8 kodiranjem. Ako se koristi neki drugi format, to je navedeno u opisu metode.
HTTP statusni kod identificira status zahtjeva – za uspješne zahtjeve vraća se statusni kod 200. Uz ovaj odgovor bit će primljene i tražene informacije s poslužitelja. Odgovori će se razlikovati ovisno o vrsti korištenog API-ja. API odgovori za različite vrste API-ja opisani su u odgovarajućim odjeljcima.
Ako je došlo do pogreške s poslanim zahtjevom, sustav će vratiti odgovornu poruku sa statusnim kodom. Uobičajeni kodovi pogrešaka:
- Kod 400 – Loš zahtjev – API zahtjev nije prepoznat.
- Kod 401 – Neovlašteno – To znači da nedostaju ili su netočni podaci za autentifikaciju;
- Kod 403 – Zabranjeno – To znači da klijent nema pravo pristupa traženom resursu ili izvršavanja tražene radnje;
- Kod 404 – Nije pronađen – To znači da traženi resurs nije pronađen.
- Kod 500 – Interna pogreška poslužitelja – obratite se tehničkoj podršci svog davatelja usluga.
Kodovi pogrešaka pružaju neke općenite informacije o vrsti pogreške, omogućujući korisniku da identificira uzrok problema.
Neki API-ji imaju opcionalne elemente (parametre) u svom odgovoru, a sustav može preskočiti opcionalne parametre iz različitih razloga (nema podataka, loši podaci, isteklo vrijeme odgovora itd.). Korisnik ne smije pretpostavljati da će određeni opcionalni podaci uvijek biti uključeni u odgovor.
Ograničenja API-ja
Svi API-ji imaju jedno jedino ograničenje:
- Ne više od 1000 zahtjeva u minuti.
Ovo ograničenje vrijedi za sve postojeće FMS API-je.
API autentifikacija
API autentifikacija i autorizacija potrebna je za kontrolu korištenja API-ja za različite klijente i njihovu integraciju s različitim sustavima. Kako bi se uputio ovlašteni zahtjev sistemskim API-jima, aplikacija klijenta koja podnosi zahtjev prvo mora dobiti API_key u ime web korisnika sustava.
Klijenti mogu dobiti API ključ samo izravnim kontaktiranjem tehničke podrške svojih pružatelja usluga. API ključ sastoji se od nasumično generiranih slova, brojeva i simbola.
Primjer zahtjeva koji koristi API_key:
Ako je API_key istekao, uklonjen ili jednostavno onemogućen, sustav će vratiti sljedeći odgovor:
API krajnje točke, parametri zahtjeva i odgovori mogu se pregledati u „Swaggeru” putem ove poveznice: https://api.fm-track.com
Bilješka
Uvijek je potrebno navesti verziju API-ja u svim vrstama API-ja.
Važno!
Zbog stalnog razvoja i API-ja i sustava od kojeg traži informacije, korisnici ponekad mogu primiti parametre koji nisu navedeni u opisima. Preporučuje se jednostavno zanemariti nepoznate parametre koji nisu dokumentirani u svakom opisu API-ja.
Verziranje i kompatibilnost
API rješenje se stalno ažurira, poboljšava i na druge načine modificira, stoga je potrebno razumjeti što znači „kompatibilnost” i kako utječe na korisnika prilikom korištenja API rješenja.
Kada se API ažurira, događa se jedna od sljedeće dvije mogućnosti:
- API je unatrag kompatibilan – to znači da napravljene promjene neće ni na koji način utjecati na tijek rada API-ja, stoga se ne stvara nova verzija.
- API nije unatrag kompatibilan – to znači da su neke API komponente promijenjene tako da više ne rade na isti način kao prije. U tom slučaju, objavljuje se nova verzija API-ja.
Što se smatra unatrag kompatibilnom API verzijom:
- Dodan je novi API resurs;
- Postojećem API-ju dodani su novi opcionalni parametri zahtjeva
- Postojećim API odgovorima dodana su nova svojstva.
- Redoslijed svojstava je promijenjen u postojećim API odgovorima.
- Promjena duljine ili formata ID-ova objekata ili drugih neprozirnih nizova.
Korisnik može sa sigurnošću pretpostaviti da ID-ovi objekata koje sustav generira nikada neće premašiti 255 znakova, ali korisnik bi trebao biti u mogućnosti rukovati ID-ovima s potencijalnom duljinom od 255 znakova. Na primjer, ako korisnik koristi MySQL, ID-ovi bi trebali biti pohranjeni u stupcu VARCHAR(255) COLLATE utf8_bin (konfiguracija COLLATE osigurava razliku između velikih i malih slova u pretragama). - Dodavanje novih ENUM tipova. – svaki sustav bi trebao elegantno obraditi sve nepoznate ENUM tipove. Ako se, na primjer, tip promijeni iz [Privatno, Poslovni] u [Privatno, Poslovni, Poslovni], to ne bi trebalo imati nikakvog učinka na sustav.