Что такое веб-сервис и их виды?

Веб-сервис — программный интерфейс, через который приложения обмениваются данными по сети, обычно через HTTP или HTTPS. Слово «сервис» также употребляют в широком смысле для онлайн-инструментов, но веб-сервис как интерфейс отличается от обычной страницы для человека.

Как взаимодействуют приложения

Клиент отправляет запрос на адрес интерфейса, а сервер возвращает ответ в согласованном формате, например JSON. API определяет доступные операции, параметры, авторизацию и возможные ошибки. Само использование HTTP не делает произвольный сайт API: интерфейс должен иметь понятный контракт для программы-клиента.

Распространённые подходы

HTTP API нередко проектируют вокруг ресурсов и стандартных методов GET, POST, PUT или DELETE. GraphQL задаёт язык запросов и схему данных. SOAP — протокол обмена структурированными сообщениями. Эти подходы решают разные задачи; выбор зависит от требований к данным, совместимости и управлению доступом. FTP, SSH и Telnet — самостоятельные сетевые протоколы, а не виды веб-сервисов.

На что смотреть пользователю API

Проверяйте актуальную документацию, ограничения частоты запросов, способы аутентификации и обработку ошибок. Не передавайте секреты в публичном URL и используйте HTTPS для конфиденциальных данных. Практический пример программного интерфейса — 2IP API; доступность конкретных методов следует сверять с его текущей документацией.

Интерфейс и контракт сервиса

Представим приложение, которое получает сведения о домене. Клиент отправляет запрос с доменным именем, сервер отвечает структурированными данными или ошибкой. Контракт должен объяснять допустимый формат имени, необходимость ключа доступа, поля ответа и ограничения использования. Если изменить смысл существующего поля без предупреждения, клиент может показать неверные данные, хотя запрос по-прежнему получает HTTP 200.

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

Методы HTTP и смысл ответа

Метод GET предназначен для получения представления ресурса и должен быть безопасным в смысле отсутствия запрошенного клиентом изменения состояния. POST передаёт данные на обработку; PUT обычно заменяет состояние указанного ресурса, а DELETE запрашивает удаление. Реальная семантика зависит от API, но стандартные методы и коды ответа помогают клиенту не делать неверных предположений.

Код 200 сообщает об успешной обработке конкретного HTTP-запроса, 201 — о создании ресурса, 400 — о проблеме с запросом, 401 — о необходимости аутентификации, 403 — об отказе в доступе, 404 — об отсутствии выбранного ресурса, 429 — об ограничении частоты. Не следует считать любую ошибку 500 доказательством неисправности сети: соединение могло быть успешным, а проблема возникла в приложении. Семантика описана в RFC 9110.

Формат данных и совместимость

JSON популярен для HTTP API, но подходит не для каждой задачи. Тело ответа может быть XML, двоичным файлом или вообще отсутствовать. Заголовок Content-Type сообщает тип переданных данных; клиент не должен угадывать его по расширению URL. Параметры запроса, часовой пояс, единицы измерения и кодировка должны быть описаны явно.

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

REST, SOAP и GraphQL

REST описывает архитектурный стиль, а не один обязательный формат URL. HTTP API может применять некоторые принципы REST, но сам факт передачи JSON по HTTPS не доказывает соответствия этому стилю. SOAP задаёт формат сообщений и связанные правила обработки; его часто встречают в системах со строгими контрактами и существующими корпоративными интеграциями.

GraphQL даёт клиенту язык запросов к типизированной схеме: клиент указывает нужные поля, а сервер выполняет запрос согласно правилам схемы. Это может сократить передачу лишних данных, но переносит часть сложности в управление запросами, авторизацией и производительностью. Сравнивать подходы полезнее по требованиям проекта, чем по утверждению, что один из них «современный», а другой «устаревший». Для исторического определения веб-сервиса см. архитектуру W3C.

Аутентификация и разрешения

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

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

Ограничение нагрузки, кеш и повторы

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

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

Практическая проверка интеграции

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

Для диагностики сохраняйте время, тип операции и безопасный идентификатор запроса, но не полный токен и не персональные данные. Отделяйте ошибку DNS от ошибки TLS, HTTP-ответа и ошибки обработки данных. Именно такой разбор помогает понять, где исправлять проблему. Пример существующего интерфейса и его текущих возможностей приведён в документации 2IP API.

Что веб-сервисом не является

Обычная страница может обращаться к API, но сама по себе не обязана предоставлять программный интерфейс стороннему клиенту. FTP передаёт файлы, SSH предоставляет защищённый удалённый доступ, а Telnet — сетевой терминальный протокол без встроенного шифрования. Их можно использовать рядом с веб-сервисом при развёртывании или эксплуатации, но называть каждый из них видом веб-сервиса неточно. Например, разработчик загружает файлы по защищённому протоколу, а уже запущенное приложение предоставляет HTTP API. Разные уровни этой работы лучше описывать отдельно: транспорт файлов, администрирование сервера и интерфейс обмена данными.

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

Один пример ответа не определяет весь сервис

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