API для чайників: Що таке API, як вони працюють?

Ви коли-небудь замислювалися над тим, як програми та веб-сайти безперешкодно працюють разом? Що ж, саме тут у гру вступає сила API. Повна форма API – це інтерфейс прикладного програмування. Простіше кажучи, ми можемо визначити його як інструмент, який допомагає різним додаткам спілкуватися один з одним, не втручаючись у внутрішні процеси. Наприклад, якщо ви використовуєте додаток для подорожей, він не просто показує вам ціни на авіаквитки. У цей момент він використовує інший сервер за допомогою API, щоб отримати дані для вас. Інший приклад – коли ви намагаєтеся увійти до свого акаунта Gmail з іншого пристрою. У цьому процесі задіяні різні API, що працюють у фоновому режимі.

Якщо ви шукали простий посібник з API для початківців, то це саме для вас!

Що таке API?

Перш ніж перейти до підручника з API для початківців, давайте коротко обговоримо питання “Що таке API?”

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

Ось деякі терміни, пов’язані з основами API, які мають вирішальне значення для розуміння того, як працює API:

• Виклик API: Виклик API також відомий як запит до API. Це повідомлення серверу, яке дозволяє API виконати певну дію. Саме виклик API запускає дію, запитувану клієнтом на веб-сайті або в додатку.
• Ключ API: Ключ API має велике значення, коли мова йде про автентифікацію виклику API. Іншими словами, він використовується для ідентифікації програми до встановлення зв’язку, щоб забезпечити безпеку даних.
• Шлюз API: Шлюзи API використовуються для обробки інформації з боку клієнта на сервер. Саме через API-шлюзи запити обробляються і пересилаються на різні сервери для формування відповіді клієнту. Таким чином, API-шлюзи допомагають координувати дії, щоб гарантувати, що запити досягають потрібних серверів і відповідь надсилається клієнту.

Як працює API?

У цьому розділі ми відповімо на найпоширеніше питання: як працюють API? Розуміти, як працюють API, важливо, особливо для розробників, адже це точка дотику для вашого проекту та вже існуючих систем. Для того, щоб зрозуміти, що таке API, слід зазначити, що API працює за моделлю “запит-відповідь”. Це означає, що клієнт надсилає запит на сервер API, а потім API отримує відповідь від сервера. З точки зору кроків, існують функціональні HTTP-запити та кінцеві точки API.

Ось як це відбувається:

Клієнт API

Клієнт починає роботу із запиту до сервера API. Клієнт надсилає HTTP-запит, який може бути в різних форматах, таких як GET, DELETE, PUT або POST. Наприклад, ви можете ввести GET-запит на кшталт “яка температура в Канаді сьогодні?”. Крім того, він може бути ініційований іншою подією, наприклад, сповіщенням від іншої підключеної програми.

Запит до API

API-запит буде виглядати по-різному залежно від API. Тим не менш, він складається з різних частин, таких як кінцева точка, метод, параметри, заголовки та тіло. Кінцева точка використовується для зв’язку і часто представлена у вигляді URL-адреси. Саме звідти API отримує запити. З іншого боку, методи, що використовуються в запиті, – це мова спілкування, яку використовує клієнт, щоб повідомити серверу, що він хоче зробити з даними. Крім того, параметри, що використовуються в API, визначають виклик API. Вони використовуються для створення унікальних кінцевих точок виклику API. Вони можуть бути представлені в тілі запиту, заголовках і URL-адресах.

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

Нарешті, є тіло запиту, яке вважається основним компонентом HTTP-запиту. Більшість з них містять операції створення та оновлення, такі як POST, PATCH і PUT. Наприклад, при створенні нового облікового запису користувача існує ймовірність того, що дані користувача, такі як його ім’я, адреса електронної пошти та пароль, будуть міститися в тілі запиту.

Сервер API

Сервер API отримує запити від клієнта API. Він відповідає за обробку запитів з боку клієнта і надає відповідні відповіді. Сервер API виконує різні операції, такі як автентифікація відповідей, валідація, вилучення та маніпуляції з даними.

Відповідь API

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

• 200 “OK” – означає, що запит виконано успішно.
• 201 “Створено” – підтверджує успішне створення ресурсу.
• 202 “Прийнято” – означає, що запит прийнято до обробки.
• 404 “Не знайдено ” – означає, що сервер не зміг знайти сторінку.
• 500 “Внутрішня помилка сервера ” – означає, що сервер зіткнувся з неочікуваною помилкою.

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

Переваги API

API дозволяють програмним системам і додаткам ефективно взаємодіяти. Деякі з переваг API включають

Автоматизація

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

Безпека

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

Інновації

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

Типи API

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

Приватні API

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

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

Публічні API

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

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

Партнерські API

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

Складені API

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

Типи API на основі архітектурних стилів

Інший спосіб класифікувати API – за архітектурними стилями. Нижче наведено деякі з найпоширеніших архітектурних стилів для API, що пояснюються для чайників:

REST API

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

Крім того, REST API використовується для додатків, які передбачають передачу даних. Іншими словами, сервер API отримує запит і надсилає вміст з цільового сервера користувачеві. Для обробки даних API використовує HTTP-методи, такі як GET, PUT, POST і DELETE. Запитувана інформація надсилається клієнт-серверу у форматі JSON або XML

SOAP API

Простий протокол доступу до об’єктів (Simple Object Access Protocol – SOAP API) використовує XML-протокол для зв’язку між клієнтською та серверною системами. На відміну від REST, який базується на архітектурі без стану, SOAP базується на строгому стандарті.

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

API WebSocket

WebSocket API забезпечують двосторонній зв’язок між клієнтською та серверною системами. На відміну від REST і SOAP, які вимагають повторних запитів для зв’язку, WebSocket забезпечує постійний канал зв’язку для оновлення даних в режимі реального часу. WebSocket API здебільшого використовується в додатках, які потребують швидкого обміну даними.

GraphQL API

GraphQL API – це мова запитів з відкритим вихідним кодом. Це альтернатива REST, що дозволяє клієнтам отримувати тільки ті дані, які їм потрібні. GraphQL дозволяє клієнтам використовувати лише одну кінцеву точку для отримання даних, замість того, щоб надсилати декілька запитів.

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

API віддаленого виклику процедур

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

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

Покрокове керівництво по створенню API

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

Ось покрокова інструкція, як це зробити:

Крок 1: Виберіть мову програмування та фреймворк

Python – одна з найпоширеніших мов програмування для створення скриптів. Python проста, легко налаштовується і має зрозумілий синтаксис. З іншого боку, Flask – це легкий веб-фреймворк, який дозволяє легко створити API за допомогою декількох кодів.

Крок 2: Створіть середовище для кодування

Наступним кроком буде налаштування вашого середовища. Ми будемо використовувати uv, сучасний інструментарій Python, який швидко витісняє старий pip + venv. Ви можете встановити uv за допомогою офіційної документації. Після встановлення створіть новий проект і встановіть Flask за допомогою наступних кодів:

# Create project folder and enter it
mkdir bar-api && cd bar-api

# Install Flask with uv (uv manages a virtual environment for you)
uv pip install flask

Крок 3: Створіть першу кінцеву точку

Тепер ми можемо написати простий додаток Flask, який працює як API бару. Спочатку створіть новий файл з ім’ям app.py і вставте код:

 

Приклад додатку Flask (меню, замовлення та кінцеві точки білінгу)

from flask import Flask, jsonify, request

app = Flask(__name__)

# Sample data: drink menu
menu = [
    {"id": 1, "name": "Root beer", "price": 5.0},
    {"id": 2, "name": "Ginger ale", "price": 6.5},
    {"id": 3, "name": "Tequila", "price": 7.0},
]

# Empty list to store orders
orders = []

# Home route
@app.route('/')
def home():
    return "Welcome to our bar!"

# GET /menu — fetch the menu
@app.route('/menu', methods=['GET'])
def get_menu():
    return jsonify(menu)

# POST /order — create a new order
@app.route('/order', methods=['POST'])
def place_order():
    new_order = request.get_json()

    if not new_order or "name" not in new_order or "price" not in new_order:
        return jsonify({"error": "Invalid order data"}), 400

    new_order["id"] = len(orders) + 1
    orders.append(new_order)

    return jsonify({"order_id": new_order["id"]}), 201

# GET /bill/<order_id> — get the bill for a specific order
@app.route('/bill/<int:order_id>', methods=['GET'])
def get_bill(order_id):
    order = next((o for o in orders if o["id"] == order_id), None)

    if order:
        return jsonify({
            "order_id": order_id,
            "total_price": order["price"]
        })

    return jsonify({"error": "Order not found"}), 404

if __name__ == "__main__":
    app.run(debug=True)

Ось розбивка коду:

• Flask створює веб-додаток і керує маршрутами (кінцевими точками, такими як /menu або /order)
• @app.route() визначає, що робить кожна URL-адреса і який метод HTTP вона підтримує
• Jsonify() відповідає за перетворення даних Python у формат JSON
• request.get_json() зчитує вхідні дані після надсилання POST-запиту
• return (data, 201 ) вказує на те, що замовлення було успішно створено
• app.run(debug=True ) запускає сервер розробки Flask

Щоб запустити його:

uv запустити python app.py

Результат: Ваш API тепер доступний за адресою http://102.1.1.0.1000/

Крок 4: Протестуйте свій API

Перед запуском необхідно протестувати роботу API. Ви можете використовувати curl – інструмент командного рядка для надсилання HTTP-запитів для запуску API. Після того, як ваш сервер Flask буде активний, відкрийте нове вікно терміналу для використання curl.

Наприклад:

Зайти на домашню сторінку сервера – (за допомогою GET-запиту)

curl http:// 102.1.1.0.1000/

Відповідь має бути приблизно такою:

“Ласкаво просимо до нашого бару!”

Крок 5: Обробка помилок

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

Прикладом помилки є надсилання HTTP-запиту на неіснуючий напій. Система сприймає це як помилку і повертає типову HTML-сторінку з повідомленням про помилку. Однак ми хочемо, щоб усі відповіді були у форматі JSON. Щоб досягти цього, нам потрібно додати кілька рядків коду в нижню частину файлу app.py, як показано нижче:

 

Приклад обробки помилок (Flask)

@app.errorhandler(404)
def not_found(e):
    return jsonify({"error": "Not found"}), 404

@app.errorhandler(400)
def bad_request(e):
    return jsonify({"error": "Bad request"}), 400

@app.errorhandler(500)
def server_error(e):
    return jsonify({"error": "Internal server error"}), 500

Ось розбивка кодів:

• Якщо маршрут не існує, повертається HTTP-повідомлення про помилку з кодом 404. Повідомлення у форматі JSON замість потворної HTML-сторінки з відповіддю про помилку.
• Якщо запит недійсний – відсутні поля або невірні дані, повертається код статусу 400
• У разі несподіваної помилки на сервері, він повертає простий код відповіді 500 в читабельному форматі

API-ключі проти токенів на пред’явника та OAuth

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

Ключі API

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

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

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

• Зв’язок між серверами: Це гарантує, що зв’язок відбувається лише між авторизованими серверами.
• Доступ до публічних API: Ключі API зазвичай використовуються для надання доступу до публічних API, таких як Google map API.
• Сторонні інтеграції: API-ключі використовуються для інтеграції вашого API сторонніми розробниками без шкоди для можливості моніторингу використання та усунення несправностей. Це особливо корисно, коли монетизація та обмеження ставок є частиною ваших цілей.

Однак ключ API не є ефективним як окреме рішення для захисту. Натомість він має бути частиною ширшої структури безпеки API.

Токени на пред’явника

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

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

Токени на пред’явника бувають різних форматів, таких як

• JSON Web Tokens (JWT): Ці токени мають криптографічний підпис і дозволяють здійснювати аутентифікацію без громадянства, що робить їх відмінним вибором для розподілених систем і мікросервісів
• Непрозорі токени: Це випадкові рядки без зв’язку з клієнт-сервером. Хоча їх легко реалізувати, вони вимагають зберігання на стороні сервера.
• Токени оновлення: Вони призначені для того, щоб власники могли отримувати нові токени доступу без необхідності повторної перевірки.

Деякі з випадків використання включають

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

OAuth (Відкрита авторизація)

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

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

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

Підсумок

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

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