API (интерфейс за програмиране на приложения) позволява на клиентите да интегрират FMS със своите системи, да изтеглят и изпращат данни за различни субекти.
Клиентът подава HTTP заявки към системата, като предоставя информация за планираното действие. HTTP командите обикновено се използват в API:
- GET – Прочитане на ресурс;
- POST – Промяна на състоянието на ресурса;
Заявеното съдържание се предоставя във формат JSON с кодиране UTF-8. Ако се използва друг формат, той се посочва в описанието на метода.
Кодът на състоянието на HTTP идентифицира състоянието на заявката – при успешни заявки се връща код на състоянието 200. Заедно с този отговор ще бъде получена и исканата информация от сървъра. Отговорите ще се различават в зависимост от вида на използвания API. Отговорите на API за различните типове API са описани в съответните раздели.
Ако при изпратената заявка е възникнала грешка, системата ще върне съобщение за отговор с код на състоянието. Често срещани кодове за грешки:
- Код 400 – Лоша заявка – заявката на API не беше разпозната.
- Код 401 – Неоторизиран – Това означава, че удостоверителните данни липсват или са неправилни;
- Код 403 – Забранено – Това означава, че клиентът няма право на достъп до искания ресурс или да извърши исканото действие ;
- Код 404 – Не е намерен – Това означава, че заявеният ресурс не е намерен.
- Код 500 – Вътрешна грешка на сървъра – моля, свържете се с техническата поддръжка на вашия доставчик.
Кодовете на грешките предоставят обща информация за вида на грешката, като по този начин позволяват на потребителя да идентифицира причината за проблема.
Някои API имат незадължителни елементи (параметри) в отговора си, като незадължителните параметри могат да бъдат пропуснати от системата по различни причини (липса на данни, лоши данни, изтичане на времето за отговор и т.н.). Потребителят не трябва да предполага, че определени незадължителни данни винаги ще бъдат включени в отговора.
Ограничения на API
Всички API имат едно-единствено ограничение:
- Не повече от 1000 заявки в минута.
Това ограничение е валидно за всички съществуващи API на FMS.
Удостоверяване на API
Удостоверяването и оторизацията на API са необходими, за да се контролира използването на API от различни клиенти и тяхната интеграция с различни системи. За да направи оторизирана заявка към системните API, заявяващото приложение на клиента трябва първо да получи API_ключ от името на системния уеб потребител.
Клиентите могат да получат API ключ само като се свържат директно с техническата поддръжка на своите доставчици на услуги. Ключът за API се състои от произволно генерирани букви, цифри и символи.
Пример за заявка, използваща API_ключ:
Ако API_ключът е изтекъл, премахнат или просто деактивиран, системата ще върне следния отговор:
Крайните точки на API, параметрите на заявките и отговорите могат да бъдат прегледани в “Swagger” чрез тази връзка: https://api.fm-track.com
Бележка
Винаги е необходимо да се посочи версия на API във всички видове API.
Важно!
Поради постоянното развитие както на API, така и на системата, от която се изисква информация, понякога потребителите могат да получат параметри, които не са посочени в описанията. Препоръчва се просто да се игнорират неизвестните параметри, които не са документирани в описанието на всеки API.
Създаване на версии и съвместимост
Решението за API постоянно се актуализира, подобрява и променя по друг начин, поради което е необходимо да се разбере какво означава “Съвместимост” и как тя влияе на потребителя при използването на решението за API.
Когато API се актуализира, се случва една от следните две възможности:
- API е обратно съвместим – това означава, че направените промени няма да повлияят по никакъв начин на работния процес на API, поради което не се създава нова версия.
- API не е обратно съвместим – това означава, че някои от компонентите на API са променени и вече не работят по същия начин, както преди. В този случай се пуска нова версия на API.
Какво се счита за обратно съвместима версия на API:
- Добавен е нов ресурс на API;
- Към съществуващия API бяха добавени нови незадължителни параметри на заявката
- Към съществуващите отговори на API бяха добавени нови свойства.
- Редът на свойствата е променен в съществуващите отговори на API.
- Промяна на дължината или формата на идентификаторите на обекти или други непрозрачни низове.
Потребителят може спокойно да приеме, че идентификаторите на обекти, които системата генерира, никога няма да надвишават 255 символа, но трябва да може да работи с идентификатори с потенциална дължина 255 символа. Например, ако потребителят използва MySQL, идентификаторите трябва да се съхраняват в колона VARCHAR(255) COLLATE utf8_bin (конфигурацията COLLATE осигурява чувствителност към малки и големи букви при търсене). - Добавяне на нови типове ENUM. – всяка система трябва да се справя с непознати типове ENUM по естествен начин. Ако например типът се промени от [Private, Business] на [Private, Work, Business], това не би трябвало да има ефект върху системата.