API от А до Я (теория и практика)

Ссылка на мой канал и ссылка на сообщество ИТ специалистов. С 30 октября стартует курс по системному анализу для прокачки до middle уровня с возможностью получения оффера в Иннотех - подробности в канале.

Вчера, сегодня, завтра, термин "API" стал обыденным, и в то же время, ключевым. За этой трехбуквенной аббревиатурой скрывается нечто гораздо более значительное, чем просто технический термин. API, или Application Programming Interface, представляет собой набор правил и инструкций, согласно которым различные программы и сервисы могут общаться между собой. Эти правила определяют, как данные и функциональность могут быть переданы от одной программы к другой, как они могут взаимодействовать и обмениваться информацией.

Почему же это так важно? Да просто вы не сможете пройти на хорошую должность не зная этого, а соответсвенно не сможете повысить свою заработную плату.

В данной статье мы поговорим о том, что представляет из себя API в теории и на практике, типа

API (Application Programming Interface) – это набор правил и протоколов, который позволяет разным программам взаимодействовать друг с другом. API определяет методы и структуры данных, которые могут быть использованы для обмена информацией и выполнения операций между различными программами или компонентами программного обеспечения.

API может быть использован для различных целей, включая:

1. Взаимодействие с внешними сервисами

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

2. Расширение функциональности

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

3. Интеграция с аппаратным обеспечением

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

4. Обмен данными

API часто применяются для обмена данными между различными частями одной программы или между разными программами.

API могут быть реализованы разными способами, включая веб-сервисы, библиотеки, SDK (Software Development Kit) и другие средства. Они обычно документированы, чтобы разработчики могли понять, как ими пользоваться, и какие функции они предоставляют.

Существует несколько типов API в зависимости от того, каким образом они предоставляют доступ к функциональности и данным. Попробуем перечислить наиболее распространенные типы (моя классификация, но без вики никуда):

Веб-API (Web APIs). Web-API предоставляют доступ к функциональности и данным через интернет с использованием стандартных протоколов, таких как HTTP. RESTful API и SOAP API - это примеры веб-API, которые позволяют взаимодействовать с удаленными веб-сервисами.
Библиотеки и SDK (Software Development Kit). Эти API предоставляются в виде библиотек или наборов инструментов, которые разработчики могут внедрить непосредственно в свои приложения. Они часто используются для работы с конкретными языками программирования или платформами.
API операционных систем. Эти API предоставляют доступ к функциям операционных систем, таким как файловая система, сеть и управление устройствами. Примеры включают WinAPI для Windows и POSIX API для Unix-подобных операционных систем.
API DB/DWH. API, предназначенные для взаимодействия с базами данных. Примеры включают JDBC для Java и SQLAlchemy для Python.
Графические API. API для создания графических интерфейсов и визуализации данных. Примеры включают DirectX и OpenGL для 3D-графики.
API социальных сетей. Популярные социальные сети, такие как Facebook, Twitter и Instagram, предоставляют API для доступа к данным и функциям своих платформ.
Файловые API. API для работы с файлами и хранилищами. Примеры включают API для облачных хранилищ, такие как Amazon S3 и Google Cloud Storage.
Микросервисные API. Используются в архитектуре микросервисов для взаимодействия между различными микросервисами.
Мобильные API. API, предназначенные для мобильных платформ, такие как Android API и iOS API.

В России очень хорошо развиты компании работающие в ФинТех, соответственно, когда мы говорим об API, то традиционно подразумеваем микросервисные API.

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

Преимущества протоколов API

1. Стандартизация

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

2. Модульность

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

3. Улучшенное взаимодействие

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

4. Безопасность

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

5. Расширяемость

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

Недостатки протоколов API

1. Сложность

Некоторые API-протоколы могут быть сложными и требовать глубокого понимания для их использования и реализации.

2. Совместимость

Изменения в протоколах API могут привести к совместимости проблемам, особенно если старые версии клиентов или серверов не поддерживают новые изменения.

3. Производительность

Некоторые протоколы могут иметь накладные расходы в виде лишнего объема данных или дополнительных запросов, что может сказаться на производительности.

Различия между протоколами API

1. RESTful API (Representational State Transfer)

RESTful API основаны на принципах архитектуры REST и используют стандартные HTTP методы (GET, POST, PUT, DELETE) для взаимодействия с ресурсами. Они часто используются для веб-сервисов и взаимодействия с данными в формате JSON или XML.

2. SOAP (Simple Object Access Protocol)

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

3. GraphQL

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

4. JSON-RPC и XML-RPC

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

Каждый протокол API имеет свои преимущества и недостатки, и выбор зависит от конкретных потребностей и контекста разработки. А теперь давайте на подробнее рассмотрим любимца публики.

Скажу так, что знание этого протокола для системного аналитика, не буду даже говорить о разработчиках (для них это азы), является необходимым минимумом для позиций уровня Middle и выше.

REST API (Representational State Transfer API) - это стиль архитектуры API, основанный на принципах архитектуры REST. REST был представлен Роем Филдингом в 2000 году в его диссертации и стал одним из популярных способов проектирования и создания веб-сервисов. Он использует стандартные HTTP методы (GET, POST, PUT, DELETE) и работает с ресурсами, представленными в виде URL-адресов.

Вот основные характеристики REST API

В REST API всё представлено в виде ресурсов, которые могут быть идентифицированы уникальными URL-адресами. Ресурсы могут быть, например, объектами, документами или коллекциями данных.
REST использует стандартные методы HTTP для выполнения операций над ресурсами. Наиболее часто используемые методы: GET, POST, PUT, DELETE.
REST API обычно работает с данными, представленными в формате JSON или XML. Ответы от сервера содержат данные, а клиенты могут отправлять данные серверу при создании или обновлении ресурсов.
RESTful сервисы не сохраняют состояние между запросами. Каждый запрос от клиента должен содержать все необходимые данные для выполнения операции. Это делает их более масштабируемыми и легче в поддержке.
REST API обладают унифицированным интерфейсом, что означает, что клиенты и серверы могут взаимодействовать между собой, следуя общим правилам, без необходимости знания подробностей реализации.

А теперь перечислим характеристики списком:

Ресурсы
HTTP Методы
Представление данных
Stateless
Однозначность (Uniform Interface)

Преимущества REST API или почему этот стиль так популярен:

Простота использования и понимания;
Стандартное использование HTTP методов и кодов состояния;
Масштабируемость и гибкость;
Возможность использования веб-кэширования для оптимизации производительности.

Недостатки REST API:

Не всегда идеально подходит для сложных операций, требующих транзакций или многоэтапных процессов;
Отсутствие строгой спецификации может привести к разнообразию реализаций и сложностям в согласованности интерфейсов.

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

Методы REST API

В этом протоколе или архитектурном стиле использует стандартные HTTP методы для выполнения операций над ресурсами. Попробую описать наиболее распространенных HTTP методы.

GET. Метод GET используется для получения данных с сервера. Клиент отправляет GET-запрос на сервер, указывая URL-адрес ресурса, который нужно прочитать. Сервер отвечает данными, находящимися по указанному URL. GET-запросы обычно не должны иметь побочных эффектов на сервере, они должны быть безопасными и идемпотентными, что означает, что повторный GET-запрос не должен изменять состояние ресурса.
POST. Метод POST используется для создания нового ресурса на сервере или для отправки данных для обработки. POST-запросы могут изменять состояние сервера и не являются идемпотентными, поскольку каждый POST-запрос может создавать новый ресурс. Обычно POST-запросы отправляют данные в теле запроса.
PUT. Метод PUT используется для обновления существующего ресурса или для создания ресурса, если он не существует. PUT-запросы должны быть идемпотентными: повторное выполнение одного и того же PUT-запроса не должно изменять состояние ресурса. Клиент отправляет данные для обновления ресурса в теле запроса.
DELETE. Метод DELETE используется для удаления ресурса с сервера. Клиент отправляет DELETE-запрос, указывая URL-адрес удаляемого ресурса. DELETE-запросы также должны быть идемпотентными: повторное выполнение DELETE-запроса на уже удаленный ресурс не должно вызывать ошибку.
PATCH. Метод PATCH используется для частичного обновления ресурса. В отличие от PUT, который обновляет ресурс полностью, PATCH позволяет обновлять только определенные части ресурса. Клиент отправляет данные, описывающие изменения, в теле запроса.
OPTIONS. Метод OPTIONS используется для запроса информации о доступных методах и параметрах для конкретного ресурса. Это полезно для проверки поддерживаемых операций сервером.
HEAD. Метод HEAD аналогичен GET, но сервер отвечает только заголовками ответа без передачи фактического содержания ресурса. Это может использоваться для проверки доступности ресурса и получения метаданных без загрузки всего ресурса.

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

Мы ничто без ТЗ, поэтому предлагаю сделать постановку требований

ТЗ

Сделайте мне бота, который будет по фамилии и городу предоставлять ник пользователей в телеграм. База есть в наличии.

Постановка как всегда не полная и надо бы обсудить с бизнесом подробности, но давайте попрактикуемся и немного пофантазируем

from flask import Flask, request, jsonify app = Flask(__name__) # Пример базы данных родственников (замените на свою реальную базу данных) relatives_db = [ {"last_name": "Федотов", "city": "Екатеринбург", "full_name": "Фёдор Федотов", "telegram_username": "@john"}, {"last_name": "Штейнер", "city": "Воронеж", "full_name": "Мария Штейнер", "telegram_username": "@alice"}, ] @app.route('/search_relatives', methods=['POST']) def search_relatives(): data = request.get_json() if "last_name" not in data or "city" not in data: return jsonify({"error": "Необходимо указать фамилию и город в запросе."}), 400 last_name = data["last_name"] city = data["city"] results = [] for relative in relatives_db: if relative["last_name"] == last_name and relative["city"] == city: results.append({"full_name": relative["full_name"], "telegram_username": relative["telegram_username"]}) return jsonify({"results": results}) if __name__ == '__main__': app.run(debug=True)

Запустили?

Этот код создает Flask-приложение, которое принимает POST-запросы на /search_relatives. Запрос должен содержать JSON-объект с фамилией и городом для поиска родственников в базе данных.

А теперь давайте потестим наше API и если вы введёте все корректно, а именно существующие в нашей базе фамилию и город, то на выход получите ник, ну, а если ошибетесь - ошибку 400

import requests # URL вашего API api_url = "http://128.0.0.1:5000/search_relatives" # Параметры запроса (фамилия и город) params = {"last_name": "Штейнер", "city": "Воронеж"} # Отправляем GET-запрос к API response = requests.post(api_url, json=params) # Проверяем статус ответа if response.status_code == 200: # Распечатываем результат data = response.json() print("Результат поиска родственников:") for relative in data["results"]: print(f"ФИО: {relative['full_name']}, Ник в Telegram: {relative['telegram_username']}") else: print(f"Ошибка: {response.status_code} - {response.text}")

Знание REST API имеет важное значение для системного аналитика по нескольким причинам:

Интеграция систем. Системный аналитик часто работает над проектированием систем, которые должны взаимодействовать с другими приложениями и сервисами. Знание REST API позволяет системному аналитику понимать, каким образом различные системы могут обмениваться данными и функциональностью.
Документирование систем. Важной частью работы системного аналитика является создание документации для систем, которые он анализирует и проектирует. Знание REST API помогает системному аналитику правильно описать, какие ресурсы и операции предоставляются API, чтобы другие разработчики и аналитики могли понять, как использовать API.
Проектирование систем. При проектировании систем системный аналитик может рассматривать REST API в качестве способа интеграции различных компонентов системы. Это позволяет создавать гибкие и расширяемые системы, которые могут взаимодействовать с внешними приложениями и сервисами.
Тестирование и отладка. Знание REST API полезно при тестировании и отладке систем. Системный аналитик может использовать знания о том, как взаимодействовать с API, чтобы проверить, что система правильно взаимодействует с внешними сервисами и обрабатывает данные.
Понимание технологического стека. REST API являются частью современных технологических стеков, и знание их работы помогает системному аналитику понимать, какие технологии используются в проектах и как они взаимодействуют друг с другом.

Т.е. знание REST API является важной частью компетенций системного аналитика, поскольку оно позволяет аналитику более эффективно работать над проектированием и интеграцией систем, а также облегчает коммуникацию с разработчиками и другими участниками проекта. Вы уж извините, но буду часто приводить, зачем это знать аналитикам, а также я являюсь преподавателем курса по системному анализу. Если вам интересно, то заходите на мой канал

t.me

Владимир Ловцов | ИТ наизнанку

Меня зовут Владимир Ловцов: аналитик, менеджер. В этом канале я буду рассказывать о буднях в ИТ с обратной стороны.

Введение

Что такое API

Типы API

Протоколы API

REST API

Немного практики

Итого, небольшое заключение