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

Я работаю с совершенно разными проектами и встречаюсь с разными технологиями: графы, пространственные данные, риалтайм обработка, ML и NER сервисы и т.п., но есть классические основы, которые должен знать каждый в ИТ от аналитиков до руководителей, так называемый фундамент без которого построить хорошую карьеру специалиста сложно. Так как я долго занимал различные аналитические должности, то прошу не обижаться, так как буду часто говорить о том для чего это аналитику.

Введение

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

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

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

План статьи

1. Теоретические аспекты

   1. Что такое API

   2. Типы API

   3. Протоколы API

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

   5. REST API

      1. Основные характеристики

      2. Преимущества и недостатки

      3. Методы

      4. Введение

2. Практика

Теоритические аспекты API

Что такое API

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

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

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

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

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

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

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

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

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

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

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

Типы API

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

1. Веб-API (Web APIs). Web-API предоставляют доступ к функциональности и данным через интернет с использованием стандартных протоколов, таких как HTTP. RESTful API и SOAP API — это примеры веб-API, которые позволяют взаимодействовать с удаленными веб-сервисами.

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

3. API операционных систем. Эти API предоставляют доступ к функциям операционных систем, таким как файловая система, сеть и управление устройствами. Примеры включают WinAPI для Windows и POSIX API для Unix-подобных операционных систем.

4. API DB/DWH. API, предназначенные для взаимодействия с базами данных. Примеры включают JDBC для Java и SQLAlchemy для Python.

5. Графические API. API для создания графических интерфейсов и визуализации данных. Примеры включают DirectX и OpenGL для 3D-графики.

6. API социальных сетей. Популярные социальные сети, такие как Facebook, Twitter и Instagram, предоставляют API для доступа к данным и функциям своих платформ.

7. Файловые API. API для работы с файлами и хранилищами. Примеры включают API для облачных хранилищ, такие как Amazon S3 и Google Cloud Storage.

8. Микросервисные API. Используются в архитектуре микросервисов для взаимодействия между различными микросервисами.

9. Мобильные API. API, предназначенные для мобильных платформ, такие как Android API и iOS API.

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

Протоколы 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 имеет свои преимущества и недостатки, и выбор зависит от конкретных потребностей и контекста разработки. А теперь давайте на подробнее рассмотрим любимца публики.

REST 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 является важной частью компетенций системного аналитика, поскольку оно позволяет аналитику более эффективно работать над проектированием и интеграцией систем, а также облегчает коммуникацию с разработчиками и другими участниками проекта. Вы уж извините, но буду часто приводить, зачем это знать аналитикам, а также я являюсь преподавателем курса по системному анализу. Ссылк

Ссылка на меня, если захочется пообщаться