Поширені помилки при створенні та проектуванні API

1. Неправильне визначення цілей та потреб користувачів API

Однією з основних помилок, яку часто допускають розробники під час створення API, є неправильне визначення цілей та потреб користувачів. Це веде до того, що API не відповідає очікуванням користувачів та не забезпечує їм необхідного функціоналу.

Під час розробки API необхідно проводити аналіз цільової аудиторії та її потреб. Це дозволяє правильно визначити функціонал, який має бути реалізований в API, та створити зручний інтерфейс для роботи з ним. Необхідно також враховувати специфіку бізнесу та завдань, які мають бути вирішені за допомогою API.

Крім того, важливо звернути увагу на зворотний зв'язок користувачів. Регулярне спілкування з ними дозволяє зрозуміти, що потрібно змінити або покращити в API, щоб воно краще відповідало їхнім потребам.

Отже, правильне визначення цілей та потреб користувачів API є ключовим моментом під час його створення. Тільки враховуючи всі особливості та вимоги користувачів, можна створити якісне та ефективне API, яке буде корисним та зручним для використання.

2. Відсутність документації чи її неповноцінність

Відсутність документації або її неповноцінність – одна з основних проблем, з якими стикаються багато компаній. Документація відіграє у процесах управління, контролю та аналізу роботи організації. Вона допомагає співробітникам легше орієнтуватися у робочих процесах, оптимізувати час та ресурси, а також запобігати можливим помилкам.

Відсутність документації або неповноцінність існуючих документів може призвести до негативних наслідків організації. По-перше, це може викликати плутанину серед співробітників та утруднити виконання завдань. Не маючи чітких інструкцій та керівних документів, співробітники можуть припускатися помилок або неефективно використовувати свої робочі ресурси.

Крім того, неповноцінна або відсутня документація може спричинити юридичні проблеми. У разі суперечок чи конфліктів із клієнтами, партнерами чи навіть співробітниками, відсутність необхідних письмових документів може спричинити серйозні збитки для компанії.

Як експерт у галузі управління та організації бізнес-процесів, я рекомендую всім компаніям приділити належну увагу створенню та підтримці якісної документації. Важливо розробити стандарти та правила оформлення документів, що забезпечують їхню повноту, точність та доступність для всіх зацікавлених сторін. Такий підхід не тільки підвищить ефективність роботи компанії, а й допоможе уникнути багатьох проблем та непорозумінь.

3. Неправильний вибір формату передачі

Неправильний вибір формату передачі даних може призвести до серйозних проблем у роботі системи передачі інформації. Як експерт, я хочу наголосити на важливості правильного використання формату передачі даних для забезпечення безпеки та ефективності роботи системи.

Однією з основних помилок, яку роблять багато користувачів є вибір незахищеного формату передачі даних, такого як HTTP замість HTTPS. Передача даних через незашифрований протокол може призвести до витоку конфіденційної інформації та можливого злому системи.

Крім того, неправильний вибір формату даних може уповільнити процес передачі інформації та зробити його менш ефективним. Наприклад, використання застарілих форматів файлів або непридатних методів стиснення даних може призвести до втрати інформації або недостатньої пропускної здатності мережі.

Тому, як експерт, я рекомендую завжди ретельно обирати формат передачі даних з огляду на вимоги безпеки, швидкості та ефективності роботи системи. Важливо бути в курсі останніх технологічних новинок та тенденцій у цій галузі, щоб мінімізувати ризики та забезпечити надійність роботи системи передачі даних.

4. Невідповідність стандартам безпеки

Недотримання стандартів безпеки є важливим для забезпечення захисту людей та майна від потенційних небезпек. Порушення цих стандартів може призвести до серйозних наслідків, включаючи травми, пожежі, аварії та інші надзвичайні ситуації.

Один із основних аспектів безпеки - це дотримання всіх встановлених норм і правил у галузі охорони праці, будівництва, енергопостачання та інших основних галузей діяльності. Наприклад, неправильно підключене електрообладнання або неякісні будівельні матеріали можуть спричинити загоряння або ураження електричним струмом.

Для експерта в галузі безпеки дуже важливо виявляти та усувати всі можливі порушення стандартів безпеки. Це включає регулярні перевірки обладнання, проведення інструктажів для персоналу, навчання працівників правилам пожежної безпеки та інші заходи.

Безпека - це не лише законодавчі норми та стандарти, а й відповідальне ставлення до своєї роботи та турбота про безпеку оточуючих.Важливо пам'ятати, що кожен інцидент, пов'язаний з недотриманням стандартів безпеки, може призвести до неприємних наслідків, тому необхідно завжди бути пильним та уважним до найдрібніших деталей.

5. Незручність коду API

Незручність коду API - це одна з найпоширеніших проблем, з якими стикаються розробники при роботі із зовнішніми інтерфейсами додатків. Це може бути викликано невідповідністю документації, недостатньою інформативністю або погано структурованим кодом.

Коли розробники стикаються з незручним кодом API, це сповільнює процес розробки, збільшує ймовірність помилок та ускладнює підтримку та розширення програми. Відсутність чіткої документації та детального опису методів API може призвести до того, що розробники витрачатимуть багато часу на вивчення коду та його аналіз.

Щоб уникнути незручності коду API, розробники повинні дотримуватися кращих практик написання API, таких як чітка та інформативна назва методів, послідовна структура коду, докладний опис та приклади використання кожного методу.

Також важливо активно спілкуватися з командою розробників та користувачами API, щоб розуміти їхні потреби та переваги. Регулярне оновлення документації та коду API допоможе підтримувати його актуальність та зручність читання.

В цілому, незручність коду API може бути вирішена за допомогою правильного підходу до написання та документування інтерфейсів програми. Це дозволить спростити роботу розробникам, підвищити якість коду та покращити користувальницький досвід.

6. Неправильне керування версіями API

Неправильне керування версіями API є однією з основних проблем, з якими стикаються розробники при створенні та підтримці API.Правильне керування версіями API дуже важливе для забезпечення сумісності та стійкості роботи системи.

Однією з основних помилок, які припускаються розробниками, є відсутність явної вказівки версії API в URL або заголовках запиту. Це може призвести до ситуації, коли зміни в структурі або логіці запитів можуть призвести до непередбачених наслідків клієнтів, які використовують стару версію API.

Крім того, неправильне керування версіями API може призвести до нераціонального витрачання ресурсів сервера. Якщо розробники не видаляють застарілі версії API після переходу на нові, це може призвести до надмірного споживання пам'яті та процесорного часу.

Для запобігання проблемам з керуванням версіями API необхідно чітко визначати правила оновлення та підтримки версій, а також стежити за їх актуальністю. Систематичне тестування оновлень та моніторинг використання різних версій API також допоможуть запобігти можливим проблемам.

В цілому, правильне управління версіями API є невід'ємною частиною розробки програм та важливим аспектом підтримки якості роботи системи.

7. Недостатнє тестування та налагодження

Недостатнє тестування та налагодження програмного забезпечення – одна з основних проблем, з якою стикаються розробники. Недостатнє тестування може призвести до помилок, які будуть помічені лише в процесі експлуатації програми, що може призвести до серйозних проблем для користувачів.

Тестування програми важливо проводити на всіх етапах її розробки – від початкового етапу до фінальної версії. Недостатнє тестування може призвести до того, що деякі помилки не будуть виявлені, що спричинить нестабільну роботу програми.

Налагодження програмного забезпечення також відіграє важливу роль у успішній розробці. Як експерт, я можу підтвердити, що налагодження програми є невід'ємною частиною процесу розробки. Саме завдяки налагодженню можна виявити та виправити помилки, які можуть виникнути під час роботи програми.

Тому налагодження та тестування програмного забезпечення повинні проводитися ретельно та систематично. Виняткову увагу необхідно приділяти перевірці всіх можливих сценаріїв використання програми, щоб забезпечити її стабільну та безпечну роботу для користувачів.

8. Відсутність зворотного зв'язку та моніторингу використання API

Відсутність зворотного зв'язку та моніторингу використання API – одна з основних проблем, з якою стикаються розробники та компанії під час роботи з інтерфейсами програмування додатків. Зворотний зв'язок відіграє важливу роль у процесі розробки API, тому що це дозволяє розробникам отримувати інформацію про те, як їх продукт використовується в реальному світі, а також отримувати зворотний зв'язок від користувачів про можливі проблеми чи покращення.

Відсутність зворотного зв'язку означає, що розробники не знають, як їх API використовується, які помилки виникають під час його використання та які функції можуть бути покращені чи додані. Це може призвести до того, що API не використовуватиметься повною мірою своїх можливостей, а користувачі будуть стикатися з проблемами при його використанні.

Крім того, моніторинг використання API відіграє в оптимізації роботи інтерфейсу. Завдяки моніторингу розробники можуть відстежувати обсяги трафіку, бачити які запити до API найпопулярніші, та оптимізувати свої сервіси під ці запити. Також моніторинг дозволяє виявити проблеми з продуктивністю та реагувати на них швидко.

Загалом відсутність зворотного зв'язку та моніторингу використання API може призвести до негативних наслідків для розробників та користувачів, тому важливо приділяти цьому питанню належну увагу під час роботи з інтерфейсами програмування додатків.

9. Неправильне масштабування та оптимізація продуктивності

Неправильне масштабування та оптимізація продуктивності – одна з найбільш поширених проблем, з якими стикаються розробники та інженери під час створення програмного забезпечення. Неправильне масштабування може призвести до збільшення часу виконання операцій, збільшення використання ресурсів та, як наслідок, погіршення загальної продуктивності системи.

Оптимізація продуктивності - це процес налаштування та покращення роботи програми, щоб вона могла виконувати завдання швидше та ефективніше. Оптимізація продуктивності може включати використання більш ефективних алгоритмів, поліпшення роботи з пам'яттю, розподіл навантаження і багато інших техніки.

Важливо розуміти, що оптимізація продуктивності повинна проводитись на всіх етапах розробки програмного забезпечення, починаючи з проектування та закінчуючи тестуванням та моніторингом працюючої системи. Помилки в масштабуванні та продуктивності можуть бути дуже дорогими у виправленні, якщо їх не виявити на ранніх етапах.

Ефективна оптимізація продуктивності вимагає командної роботи та взаємодії різних фахівців – розробників, тестувальників, адміністраторів та аналітиків. Тільки спільні зусилля можуть призвести до створення високопродуктивних та надійних систем.

Зверніть увагу на масштабування та оптимізацію продуктивності вже на етапі проектування системи, враховуйте потенційні проблеми та ризики та працюйте над ними протягом усього життєвого циклу проекту. У результаті це дозволить створити ефективне та масштабоване програмне забезпечення, яке успішно функціонуватиме і розвиватиметься довгий час.

10. Несвоєчасне оновлення API та його документації

Несвоєчасне оновлення API та його документації може серйозно зашкодити роботі проекту та викликати негативні наслідки для його користувачів.

Розглянемо, наприклад, ситуацію, коли розробники необхідні зміни в API роблять із запізненням. Це може призвести до того, що вже написані підключення до API старіють та перестають коректно функціонувати. Користувачі можуть зіткнутися з проблемами доступу до даних, помилками в роботі програм або навіть повним вимкненням сервісів.

Крім того, неактуальна документація API може створити плутанину у розробників, утруднити розуміння роботи інтерфейсу і ускладнити інтеграцію з сервісом. Неповна або неправильна інформація може викликати помилки в коді, і, зрештою, призвести до того, що програми працюватимуть некоректно або зовсім перестануть взаємодіяти з API.

Тому важливо проводити регулярне оновлення API та його документації, забезпечуючи своєчасне інформування розробників про зміни та надаючи актуальні інструкції щодо роботи з інтерфейсом. Такий підхід дозволить уникнути проблем, пов'язаних з неактуальністю API, та забезпечить безперебійну роботу сервісу для всіх користувачів.

Рекомендації щодо обробки помилок REST API

REST — це архітектура без збереження стану, в якій клієнти можуть отримувати доступ до ресурсів на сервері та керувати ними. ресурсів.

У цьому посібнику ми дізнаємося про деякі передові методи обробки помилок REST API, включаючи корисні підходи до надання користувачам відповідної інформації, приклади з великих веб-сайтів та конкретну реалізацію з використанням прикладу програми Spring REST.

2. Коди стану HTTP

Коли клієнт запитує до HTTP-сервера — і сервер успішно отримує запит — сервер повинен повідомити клієнта, був успішно оброблений запит чи ні.

HTTP виконує це за допомогою п'яти категорій кодів стану:

• 100-й рівень (інформаційний) - сервер підтверджує запит
• 200-й рівень (Успіх) – сервер виконав запит, як і очікувалося.
• 300-й рівень (перенаправлення) - клієнту необхідно виконати подальші дії для виконання запиту
• 400-й рівень (помилка клієнта) - клієнт відправив невірний запит
• 500-й рівень (помилка сервера) — серверу не вдалося виконати дійсний запит через помилку на сервері.

На основі коду відповіді клієнт може припустити результат конкретного запиту.

3. Обробка помилок

Першим кроком в обробці помилок є надання клієнту належного коду стану.

3.1.

Найпростіший спосіб обробки помилок відповісти відповідним кодом стану.

Ось деякі поширені коди відповідей:

• 400 Bad Request — клієнт відправив неправильний запит, наприклад, відсутній текст запиту або параметр.
• 401 Unauthorized – клієнт не пройшов аутентифікацію на сервері.
• 403 Forbidden — клієнт пройшов автентифікацію, але не має дозволу на доступ до ресурсу.
• 404 Not Found - запитаний ресурс не існує
• 412 Precondition Failed — одна або кілька умов у полях заголовка запиту оцінюються як помилкові.
• 500 Internal Server Error — загальна помилка на сервері.
• 503 Service Unavailable — Доступна послуга недоступна.

Незважаючи на простоту, ці коди дозволяють клієнту зрозуміти загальний характер помилки. Ми знаємо, що якщо ми отримуємо, наприклад, помилку 403, нам не вистачає прав доступу до ресурсу, який ми запитуємо. Тим не менш, у багатьох випадках нам необхідно надати додаткову інформацію у наших відповідях.

500 помилок сигналізують у тому, що з обробці запиту на сервері виникли проблеми чи винятки. Як правило, ця внутрішня помилка не є справою нашого клієнта.

Тому, щоб звести до мінімуму подібні відповіді клієнту, ми повинні старанно намагатися обробляти або виявляти внутрішні помилки та по можливості відповідати іншими відповідними кодами стану.

Наприклад, якщо виникає виняток через те, що запитаний ресурс не існує, ми маємо показати це як помилку 404, а не 500.

Це не означає, що 500 ніколи не слід повертати, а тільки те, що його слід використовувати в непередбачених умовах, таких як збій служби, які не дозволяють серверу виконати запит.

3.2. Відповіді на помилки Spring за замовчуванням

Ці принципи настільки всюдисущі, що Spring кодифікував їх у механізмі обробки помилок за умовчанням.

Для демонстрації припустимо, що у нас є простий додаток Spring REST, який керує книгами, з кінцевою точкою для отримання книги за її ідентифікатором:

curl -X GET -H "Accept: application/json" http://localhost:8082/spring-rest/api/book/1

Якщо немає книги з ідентифікатором 1, ми очікуємо, що наш контролер видасть виняток BookNotFoundException.

Виконуючи GET на цій кінцевій точці, ми бачимо, що цей виняток був згенерований, і це тіло відповіді:

"timestamp":"2019-09-16T22:14:45.624+0000",


"status":500,


"error":"Internal Server Error",


"message":"No message available",


"path":"/api/book/1"


>

Зверніть увагу, що цей обробник помилок за промовчанням включає мітку часу виникнення помилки, код стану HTTP, заголовок ( поле помилки ), повідомлення, якщо повідомлення включені до помилки за промовчанням (і за промовчанням порожньо), та URL-адресу. де сталася помилка.

Ці поля надають клієнту або розробнику інформацію, яка допомагає усунути проблему, а також є кілька полів, що утворюють стандартні механізми обробки помилок.

Також зверніть увагу, що Spring автоматично повертає код стану HTTP 500, коли видається наш виняток BookNotFoundException. Хоча деякі API будуть повертати код стану 500 або інші загальні коди, як ми побачимо з API Facebook та Twitter, для простоти для всіх помилок краще використовувати конкретний код помилки, коли це можливо.

У нашому прикладі ми можемо додати @ControllerAdvice, щоб у разі виключення BookNotFoundException наш API повертав статус 404 для позначення Not Found замість 500 Internal Server Error.

3.3. Більш докладні відповіді

Як видно з наведеного вище прикладу Spring, іноді код стану недостатньо, щоб показати особливості помилки.За потреби ми можемо використовувати тіло відповіді, щоб надати клієнту додаткову інформацію.

Надаючи докладні відповіді, ми повинні містити:

• Помилка – це унікальний ідентифікатор помилки.
• Повідомлення - коротке повідомлення, зрозуміле людині.
• Detail — докладніше пояснення помилки.

Наприклад, якщо клієнт надсилає запит з неправильними обліковими даними, ми можемо надіслати відповідь 401 з цим тілом:

"error":
"auth-0001",


"message":
"Incorrect username and password",


"detail":
"Ensure that the username and password included in the request are correct"


>

Поле помилки не повинно збігатися з відповідним кодом. Натомість це має бути код помилки, унікальний для нашої програми. Як правило, для поля помилки не існує угоди, чекайте, що воно буде унікальним.

Зазвичай це поле містить лише буквено-цифрові та сполучні символи, такі як тире або підкреслення. Наприклад, 0001 , auth-0001 та невірний-користувач-пароль є канонічними прикладами кодів помилок.

Частина тіла повідомлення зазвичай вважається презентабельною в інтерфейсах користувача. Отже, ми повинні перекласти цю назву, якщо ми підтримуємо інтернаціоналізацію. Тому, якщо клієнт надсилає запит із заголовком Accept-Language , що відповідає французькій мові, значення заголовка має бути перекладено французькою мовою.

Детальна частина призначена для використання розробниками клієнтів, а не кінцевим користувачем тому переклад не потрібен.

Крім того, ми також можемо надати URL-адресу, наприклад поле довідки , яким клієнти можуть перейти, щоб дізнатися більше інформації:

"error":
"auth-0001",


"message":
"Incorrect username and password",


"detail":
"Ensure that the username and password included in the request are correct",


"help":
"https://example.com/help/error/auth-0001"


>

Іноді ми можемо захотіти повідомити більш ніж одну помилку для запиту.

У цьому випадку ми маємо повернути помилки списком:

"errors":
[





"error":
"auth-0001",


"message":
"Incorrect username and password",


"detail":
"Ensure that the username and password included in the request are correct",


"help":
"https://example.com/help/error/auth-0001"


>,


.


]


>

І коли виникає одиночна помилка, ми відповідаємо списком, що містить один елемент.

Зверніть увагу, що відповідь з кількома помилками може бути надто складною для простих програм. У багатьох випадках достатньо вказати першу чи значну помилку.

3.4. Стандартизовані органи реагування

Хоча більшість REST API слідують подібним угодам, особливості зазвичай різняться, включаючи імена полів та інформацію, що у тіло відповіді. Ці відмінності заважають бібліотекам та платформам однаково обробляти помилки.

Прагнучи стандартизувати обробку помилок REST API, IETF розробила RFC 7807, який створює узагальнену схему обробки помилок .

Ця схема складається з п'яти частин:

1. type – ідентифікатор URI, який класифікує помилку
2. заголовок — коротке повідомлення, що читається легко, про помилку
3. status – код відповіді HTTP (необов'язково)
4. Detail – зрозуміле пояснення помилки.
5. екземпляр - URI, який ідентифікує конкретне виникнення помилки.

Замість використання власного тіла відповіді на помилку ми можемо перетворити наше тіло:

"type":
"/errors/incorrect-user-pass",


"title":
"Увімкнути username або password.",


"status":
401,


"detail":
"Аутентифікація вірогідна до incorrect username або password.",


"instance":
"/login/log/abc123"


>

Зверніть увагу, що поле типу класифікує тип помилки, а instance ідентифікує конкретне виникнення помилки аналогічно класам та об'єктам відповідно.

Використовуючи URI, клієнти можуть слідувати цим шляхом, щоб знайти додаткову інформацію про помилку , точно так, як посилання HATEOAS можна використовувати для навігації по REST API.

Дотримуватися RFC 7807 необов'язково, але це вигідно, якщо потрібно одноманітність.

4. Приклади

Вищезгадані методи поширені у деяких із найпопулярніших REST API. Хоча конкретні імена полів або форматів можуть різнитися на різних сайтах, загальні шаблони практично універсальні.

4.1. Твіттер

Давайте надішлемо запит GET без надання необхідних даних аутентифікації:

curl -X GET https://api.twitter.com/1.1/statuses/update.json?include_entities=true

API Twitter відповідає помилкою з цим тілом:

"errors":
[





"code":215,


"message":"Bad Authentication data."


>


]


>

Ця відповідь включає список, що містить одну помилку з її кодом помилки та повідомленням. У випадку з Twitter докладне повідомлення відсутнє, і для позначення того, що автентифікація не вдалася, використовується загальна помилка, а не конкретніша помилка 401.

Іноді простіше реалізувати загальніший код стану Як ми побачимо в нашому прикладі Spring нижче. Це дозволяє розробникам перехоплювати групи винятків і не розрізняти код стану, який має бути повернутий. Однак по можливості слід використовувати конкретний код стану.

4.2. Фейсбук

Подібно до Twitter, Facebook Graph REST API також включає докладну інформацію у свої відповіді.

Давайте виконаємо запит POST для аутентифікації за допомогою Facebook Graph API:

curl -X GET https://graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz

Ми отримуємо цю помилку:

"error":



"message":
"Missing redirect_uri parameter.",


"type":
"OAuthException",


"code":
191,


"fbtrace_id":
"AWswcVwbcqfgrSgjG80MtqJ"


>


>

Як і Twitter, Facebook також використовує загальну помилку замість більш конкретної помилки рівня 400 для позначення збою. Крім повідомлення та числового коду Facebook також включає поле типу , яке класифікує помилку, і ідентифікатор трасування ( fbtrace_id ), який діє як внутрішній ідентифікатор служби підтримки .

5. Висновок

У цій статті ми розглянули деякі з найкращих практик обробки помилок REST API:

• Надання конкретних кодів стану
• Включення додаткової інформації до органів реагування
• Єдина обробка винятків

Хоча деталі обробки помилок залежать від програми, ці загальні принципи застосовні майже до всіх REST API, і їх слід дотримуватись, коли це можливо.

Це не тільки дозволяє клієнтам послідовно обробляти помилки, але також спрощує код, який ми створюємо під час реалізації REST API.

Код, зазначений у цій статті, доступний GitHub .

• 1. Огляд
• 2. Коди стану HTTP
• 3. Обробка помилок
  • 3.1. Основні відповіді
  • 3.2. Відповіді на помилки Spring за замовчуванням
  • 3.3. Більш докладні відповіді
  • 3.4. Стандартизовані органи реагування
  • 4.1. Твіттер
  • 4.2. Фейсбук