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_key від імені веб-користувача системи.
Клієнти можуть отримати API-ключ, звернувшись безпосередньо до служби технічної підтримки свого постачальника послуг. API-ключ складається з випадково згенерованих букв, цифр і символів.
Приклад запиту з використанням API_key:
Якщо термін дії API_key закінчився, його вилучено або просто вимкнено, система поверне наступну відповідь:
Кінцеві точки 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. Наприклад, якщо тип змінюється з [Приватний, Бізнес] на [Приватний, Робота, Бізнес], це не повинно мати жодних наслідків для системи.