{"canonical_url":"https://engineer.company/uk/glossary/api/","content_markdown":"# API\n\n## Що це таке\n\nAPI (від англ. application programming interface, прикладний програмний інтерфейс) — це\nопублікований набір операцій, які програмне забезпечення відкриває для іншого програмного\nзабезпечення: як називається кожна операція, що вона приймає, що повертає і як повідомляє про\nпроблеми. Той, хто викликає, знає лише цю поверхню й нічого з того, що за нею. Тому програму з\nіншого боку можна переписати, перенести на іншу машину або розділити на три частини, а клієнт\nпрацюватиме далі, доки поверхня тримається.\n\nСлово охоплює кілька рівнів. API бібліотеки — це функції та типи, які вона експортує і які\nвикликають у межах одного процесу. API операційної системи — це її системні виклики, і POSIX\nстандартизує спільний їх набір, тож програму, написану під `open` і `read`, можна зібрати для\nкількох Unix-подібних систем. Веб-API доступний через мережу, майже завжди через HTTP, і саме\nйого сьогодні найчастіше мають на увазі: сервер, що відповідає на запити за адресами на кшталт\n`/v1/orders`, зазвичай із JSON у тілі.\n\nВеб-API бувають кількох стилів. Ресурсно орієнтовані, які часто називають REST-подібними, дають\nкожній сутності власну адресу й використовують методи HTTP, щоб її читати та змінювати. RPC-подібні,\nяк-от gRPC, відкривають іменовані процедури з аргументами й результатами, оголошеними заздалегідь.\nGraphQL має одну точку входу та одну систему типів, а клієнт пише запит, у якому перелічує саме ті\nполя, які хоче отримати. Вебхуки обертають напрямок: постачальник сам викликає адресу, яку\nзареєстрував клієнт, коли щось стається.\n\nТри сусідні поняття з ним часто плутають. Протокол, як-от HTTP, визначає, як передаються\nповідомлення; API — це те, що конкретний сервіс каже цим протоколом. SDK — це бібліотека однією\nмовою програмування, яка обгортає чужий API, щоб розробник викликав функцію, а не складав\nзапити вручну. А реалізація — це код за API, який тому, хто викликає, читати зовсім не\nпотрібно.\n\n## Чому це важливо\n\nAPI — це частина системи, на якій будують інші, тому він є обіцянкою, що живе довше за код,\nякий за ним стоїть. Переписати обробник можна за пообіддя. Змінити те, що він повертає, означає\nризикнути застосунком, уже встановленим на телефонах клієнтів, нічним імпортом партнера або\nскриптом, автора якого вже ніхто не пам'ятає.\n\nОтже, перше рішення стосується аудиторії. Приватний API, яким користується лише фронтенд\nвласної команди, можна змінити в тому самому pull request, що й його єдиного клієнта.\nПублічний API змінюють через оголошення застарілим і попередження, і кожне поле, яке він\nвіддає, доведеться підтримувати, доки хтось його читає.\n\nДруге рішення — наскільки суворим буде контракт. Суворий API оголошує тип і межу для кожного\nвхідного значення, відхиляє те, чого не знає, і на кожну помилку відповідає точним кодом\nстатусу. Він ловить помилки на вході, і його легше документувати, тестувати й генерувати для\nнього клієнтів. Поблажливий API приймає все, що надійшло, і робить, що може. Перший місяць це\nздається дружнім, а потім кожна випадкова риса реалізації стає поведінкою, на яку хтось\nпокладається. Суворість коштує часу на проєктування одразу; поблажливість коштує більше згодом,\nу момент, якого ніхто не обирає.\n\nТретє рішення стосується чужих API. Платіжний провайдер, картографічний сервіс чи мовна модель\n— це API, який продукт викликає, але не контролює: ціни змінюються, версії виводять з обігу,\nквоти зменшуються. Якщо викликати постачальника напряму з п'ятдесяти місць, перехід до іншого\nстане переписуванням. Якщо викликати його з одного модуля, яким володіє команда, перехід\nзведеться до зміни цього модуля. Обгортка коштує трохи опосередкованості й дає вихід.\n\nSemantic Versioning дає цій обіцянці словник: старший номер версії зростає, коли публічний API\nзмінюється несумісно, тож клієнт за самою версією бачить, чи безпечне оновлення. У HTTP є\nкілька способів позначити несумісну зміну, і RFC 9205, настанова IETF для протоколів на основі\nHTTP, серед них називає нове відношення посилання, новий тип медіа й нове поле заголовка.\n\n## Як це виглядає на практиці\n\nКілька проєктів на цьому сайті будували свій API навколо одного питання: що належить до API, а\nщо — до іншого місця.\n\nНа NextMariner, морській платформі для професійних контактів, відгуків про компанії та спонсорованого навчання, засновниця компанії в межах свого архітектурного внеску, зокрема, [навмисно залишила Go API тонким](/uk/portfolio/a-maritime-platform-built-in-clean-layers/). Побудований на Huma поверх Fiber, він маршрутизує, перевіряє запит, застосовує фільтрацію з міркувань безпеки й оркеструє, але не містить жодної бізнес-логіки. Правила живуть у функціях PostgreSQL, тож зміна правила відбувається в одному шарі, у SQL. Межі записали й забезпечили їх дотримання під час рев'ю. Це робить API нудним адаптером у доброму сенсі.\n\nСпоріднений проєкт виніс з API ще й формування відповідей.\n[Функції PostgreSQL збирають кожну відповідь як JSON](/uk/portfolio/designed-a-json-passthrough-from-postgres-to-api/),\nа обробник на Go отримує її як `json.RawMessage` і пересилає без змін через невеликий помічник\n`QueryJSON`. DTO, мапери й структури відповідей, які зазвичай накопичує багатошаровий API,\nвідпали, код обробників став значно коротшим, а фронтенд перестав залежати від Go. Варто\nназвати й ціну: форма відповідей API тепер визначена в SQL, тож саме там рецензент читає\nконтракт.\n\nAPI, до якого може дістатися будь-хто, мусить і захищатися. Публічний каталог компаній і\nфахівців стоїть за\n[22 обмежувачами частоти запитів, кожен для свого шляху](/uk/portfolio/built-fail-closed-rate-limiting-and-anti-abuse/),\nа їхній стан зберігається в Redis, тож ліміт діє для всіх екземплярів. Коли Redis зникає,\nобмежувачі закриваються й відхиляють трафік. Навколо них — Cloudflare Turnstile, 351 рядок\nпроміжного ПЗ для ідемпотентності, щоб повторений запис не перетворився на два, блокування\nджерела та окрема перевірка-виклик на самому каталозі. Ціну сторінка називає прямо: проблема з\nRedis стає проблемою, яку бачать користувачі, і цей варіант обрали замість проблеми з Redis,\nщо закінчується рахунком.\n\n## Де виникають проблеми\n\nЗбої API зазвичай з'являються пізно, коли клієнтів і даних уже стало більше.\n\n**Перейменоване поле ламає клієнта, про якого ніхто не знав.** Щойно API опубліковано, хтось\nпокладається на кожну видиму деталь: назви полів, порядок у списку, формулювання повідомлення\nпро помилку. Перейменуйте `customer_name` на `name` — і партнерська інтеграція зламається на\nпершому ж запиті. Змінюйте натомість додаванням: покладіть нове поле поруч зі старим, позначте\nстаре застарілим, стежте за журналами, доки його перестануть читати, і приберіть його лише в\nновій старшій версії.\n\n**Ендпоінт зі списком щомісяця сповільнюється.** Він повертає всі рядки, що підпадають під\nзапит; із п'ятдесятьма записами на старті це працювало, а на двохстах тисячах закінчується\nтайм-аутом. Додайте пагінацію з першого релізу: типовий розмір сторінки й жорстку\nмежу, яку клієнт не може перевищити. Для великих або активних колекцій курсор кращий за зсув\n(offset): зі зсувом рядок, вставлений між двома запитами, виштовхує інший рядок на наступну\nсторінку, і клієнт читає його двічі.\n\n```http\nGET /v1/orders?limit=50\u0026after=ord_8f2c HTTP/1.1\nHost: api.example.com\n```\n\n**Один покупець бачить замовлення іншого.** API перевіряє, що той, хто викликає, увійшов у\nсистему, а потім завантажує `/v1/orders/42` лише за ідентифікатором, тож, змінюючи число в\nадресі, можна гортати чужі дані. Автентифікація відповіла на питання, хто викликає; ніхто не\nспитав, чи належить цьому користувачеві замовлення 42. Обмежуйте кожен пошук власником у самому\nзапиті до бази й тримайте тест, який входить як один обліковий запис і запитує записи іншого.\n\n**Відповідь містить стовпці, які ніхто не збирався публікувати.** Ендпоінт серіалізує рядок\nбази даних або об'єкт ORM як є, тож хеш пароля, внутрішній прапорець чи закупівельна ціна\nпостачальника йдуть до кожного клієнта, а стовпець, доданий наступного року, стає публічним у\nдень, коли його створили. Та сама помилка на вході дає запиту змогу встановити `role` або\n`is_admin`, просто додавши поле в тіло. Дайте кожному ендпоінту явні типи входу й виходу з\nпереліком дозволених полів, щоб публікація поля стала свідомим рішенням.\n\n## Що почитати далі\n\n- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — методи, коди статусу\n  й заголовки, з яких складається кожен веб-API, у визначенні IETF.\n- [RFC 9205: Building Protocols with HTTP](https://www.rfc-editor.org/rfc/rfc9205) — найкраща\n  поточна практика проєктування застосунку поверх HTTP, зокрема того, як його розвивати.\n- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457) —\n  стандартна JSON-форма для відповідей із помилками, щоб клієнти розбирали кожен збій однаково.\n- [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585) — де\n  визначено 429 Too Many Requests і заголовок `Retry-After` для клієнтів, яких обмежують.\n- [Semantic Versioning 2.0.0](https://semver.org/) — правила, за якими несумісну зміну API\n  позначають номером версії.\n\n\u003chttps://engineer.company/uk/glossary/api/\u003e\n","date_modified":"2026-11-08T02:22:23Z","description":"Що таке API, чому його форма живе довше за код, як змінювати його, не ламаючи клієнтів, і чотири помилки, що спливають у продакшні.","formats":{"gemtext":"https://engineer.company/uk/glossary/api/index.gmi","gopher":"https://engineer.company/uk/glossary/api/gophermap","html":"https://engineer.company/uk/glossary/api/","json":"https://engineer.company/uk/glossary/api/index.json","markdown":"https://engineer.company/uk/glossary/api/index.md","pdf":"https://engineer.company/uk/glossary/api/index.pdf"},"kind":"page","language":"uk","title":"Що таке API?","url":"https://engineer.company/uk/glossary/api/","version":1}