API для чайников: Что такое API, как они работают?

Вы когда-нибудь задумывались, как приложения и веб-сайты работают вместе? Вот тут-то и проявляется сила API. Полное название API — Application Programming Interface. Проще говоря, мы можем определить его как инструмент, который помогает различным приложениям общаться друг с другом, не нарушая внутренних процессов. Например, если вы пользуетесь туристическим приложением, оно не просто показывает вам цены на авиабилеты. В этот момент оно использует другой сервер с помощью API, чтобы получить данные для вас. Другой пример — когда вы пытаетесь войти в свой аккаунт Gmail с другого устройства. В этом процессе задействованы различные API, работающие в фоновом режиме.

Если вы искали простое руководство по API для «чайников», то эта книга для вас!

Что такое API?

Прежде чем перейти к учебнику по API для начинающих, давайте вкратце обсудим вопрос «Что такое API?»

Application Programming Interface можно определить как набор правил, который работает как посредник между двумя или более приложениями. Предположим, вы, как клиент, хотите купить в магазине говяжье мясо, которое будет доставлено с фермы. Магазину в этом случае не нужно знать внутреннюю работу фермы, чтобы доставить клиенту свежее мясо. То же самое касается и 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 в веб-программировании. Причина их популярности — простота и масштабируемость, а также возможность интеграции с различными приложениями. Он основан на архитектуре stateless, что означает, что вся информация передается вместе с вызовом API и не зависит от предыдущих вызовов.

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

API SOAP

API Simple Object Access Protocol-SOAP использует протокол XML для взаимодействия клиентских и серверных систем. В отличие от REST, который основан на архитектуре без статических данных, SOAP базируется на строгом стандарте.

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

WebSocket API

API WebSocket обеспечивают двустороннюю связь в системах клиента и сервера. В отличие от REST и SOAP, которые требуют повторных запросов для обмена данными, WebSocket обеспечивает постоянный канал связи для обновления данных в режиме реального времени. API WebSocket чаще всего используется в приложениях, требующих быстрого обмена данными.

API GraphQL

GraphQL API — это язык запросов с открытым исходным кодом. Это альтернатива REST, позволяющая клиентам получать только те данные, которые им нужны. GraphQL позволяет клиентам использовать только одну конечную точку для получения данных, а не отправлять несколько запросов.

Поэтому легче избежать передачи ненужных данных между клиентом и сервером. В результате GraphQL API подходит для использования в приложениях, которые работают со сложными данными. Обычно он используется в приложениях и на веб-сайтах, где важна скорость работы.

API-интерфейсы удаленного вызова процедур

API RPC был создан компанией 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 run python app.py

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

Шаг 4: Протестируйте свой API

Перед запуском необходимо протестировать работу API. Для запуска API можно использовать curl — инструмент командной строки для отправки HTTP-запросов. Когда ваш сервер 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 vs Токены носителя vs OAuth

API-ключи, токены на предъявителя и OAuth играют важнейшую роль в обеспечении безопасности API. Знание их различий поможет вам понять, когда следует использовать каждый из них. Давайте объясним их в деталях

Ключи API

Ключ API — это буквенно-цифровая строка кода, которую сервер API может использовать для идентификации вызывающего пользователя API и проверки его подлинности. Основная цель ключа API — идентифицировать вызывающего пользователя и определить, авторизован ли он для доступа. Они часто используются в аналитике, ограничении скорости и мониторинге использования.

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

Поскольку API-ключи — это отличный способ подтвердить личность вызывающего API, они идеально подходят для:

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

Однако ключ API не эффективен в качестве единственного решения для обеспечения безопасности. Вместо этого он должен быть частью более широкой структуры безопасности API.

Жетоны на предъявителя

Токен на предъявителя — это токен безопасности, который предоставляет доступ своему владельцу. Это означает, что любой, у кого есть токен, получает неограниченный доступ. Подумайте об этом, как о билете в кино — тот, кто им владеет, получает доступ в кинотеатр без каких-либо других доказательств проверки.

Токены на предъявителя обычно связаны с определенным разрешением или пользовательской сессией. В отличие от ключей API, они имеют короткий срок действия и часто истекают в течение нескольких минут или часов. Однако они более безопасны, чем ключи API, особенно при использовании HTTPS.

Токены на предъявителя бывают разных форматов, например:

• JSON Web Tokens (JWT): Эти токены имеют криптографическую подпись и обеспечивают аутентификацию без статических данных, что делает их отличным выбором для распределенных систем и микросервисов.
• Непрозрачные маркеры: Это случайные строки, не имеющие никакой связи с клиентом и сервером. Хотя их легко реализовать, они требуют хранения на стороне сервера.
• Обновляемые жетоны: Предназначены для того, чтобы владельцы могли получить новые токены доступа без необходимости повторной проверки.

Некоторые из вариантов использования включают:

• Коммуникация между микросервисами: Токены на предъявителя обеспечивают безопасное взаимодействие между сервисами. Здесь один сервис аутентифицирует свой запрос к другому сервису с помощью маркера.
• Управление сеансами без сохранения информации: Эти токены позволяют серверам аутентифицировать запросы без сохранения информации о сеансе, что очень удобно для распределенных систем.
• Аутентификация в мобильных приложениях: Токены на предъявителя позволяют пользователям получать доступ к функциям приложения без необходимости повторной аутентификации.

OAuth (открытая авторизация)

OAuth — это открытый стандартный протокол авторизации. Он позволяет серверам, которые не интегрированы напрямую, предоставлять аутентифицированный доступ к информации. Этот протокол позволяет пользователям разрешить одному приложению взаимодействовать с другим от их имени, не передавая свои учетные данные для аутентификации.

OAuth имеет более сложную реализацию, чем API-ключи. Он требует явного согласия пользователя на доступ приложения к определенным данным, что делает их очень безопасными. Это недолговечные маркеры доступа и обновления, генерируемые с помощью динамического фреймворка.

OAuth работает по механизму делегирования — пользователи полагаются на сервер авторизации для создания маркеров доступа, которые можно использовать для входа в другие приложения. Например, пользователь Gmail хочет, чтобы Facebook получил доступ к списку его контактов, не сообщая при этом имя пользователя и пароль от почты.

Отзыв

В этой статье «API для чайников» мы узнали, как работают API, их типы и преимущества для бизнеса. Application Programming Interface — API — это жизненно важный компонент при создании приложений и веб-сайтов.

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