Структура Web API запросов и ответов на примере SOAP и REST

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

Начнём с SOAP или Simple Objects Access Protocol – протокол созданный в далёком 1998 компанией Microsoft и ставший стандартом в 2003 году по рекомендации W3C. SOAP может передавать информацию с помощью разных сетевых протоколов: HTTP/HTTPS, SMTP, TCP, UDP. Он поддерживает передачу данных только в XML формате и строго следует предустановленным стандартам, таким как структура обмена сообщениями, набор правил кодирования и соглашение о предоставлении процедурных запросов и ответов. SOAP обеспечивает способ связи между приложениями, работающими в разных операционных системах, с разными технологиями и языками программирования. Больше информации по спецификации SOAP можно почитать на W3C.

XML (или Extensible Markup Language) - это текстовый формат, который устанавливает набор правил для структурирования сообщений как в виде записей, удобочитаемых человеком, так и машиночитаемых. Но XML многословен, поскольку он направлен на создание веб-документа со всей его формальностью.

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

Конверт (Envelope) - это основной и важный элемент каждого сообщения, которое начинается и заканчивается сообщениями с его тегами, которые охватывают его, отсюда и название.

Заголовок (Header) -необязательный элемент, определяет специфику, дополнительные требования к сообщению, например аутентификация.

Тело (Body) включает запрос или ответ в XML формате.

Ошибка (Fault) - необязательный элемент, показывает все данные о любых ошибках, которые могут возникнуть в запросе и ответе API. 

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

POST /services/isbnservice.wso HTTP/1.1
Host: webservices.daehosting.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
 
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
 <soap12:Body>
   <IsValidISBN13 xmlns="http://webservices.daehosting.com/ISBN">
     <sISBN>string</sISBN>
   </IsValidISBN13>
 </soap12:Body>
</soap12:Envelope>

Стуктура запроса

REST акроним Representational State Transfer, это архитектурный стиль для создания веб-сервисов, взаимодействующих через протокол HTTP. Этот принцип пришёл на замену старым способам обмена информации и стал популярным благодаря своей масштабируемости и гибкости, остаётся «золотым» стандартом для публичных API.

POST /post HTTP/1.1
Host: postman-echo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 12
 
strange=boom

Любой REST запрос состоит из 4х основных частей: HTTP метода, адресата, заголовков и тела.

HTTP методы описывают что будет сделано с ресурсом. Существует 4 базовых метода описывающих принцип CRUD (create, read, update, delete): POST, GET, PUT или PATCH, DELETE. Также существуют и другие  HTTP методы, но о них мы поговорим в нашей следующей статье.

Адресат (Endpoint) содержит унифицированный идентификатор ресурса (URI), указывающий, где и как найти ресурс в Интернете. Наиболее распространенный тип URI — это уникальное расположение ресурса (URL), служащее полным веб-адресом. На картинке показан пример того, как может выглядеть URI.

User-info – опциональная часть URI в которой может указываться имя пользователя и пароль в формате user:password. По соображениям безопасности не стоит передавать пароль таким образом, только если не передавать пустую строку в качестве пароля, что указывает на его отсутствие.

Host – часть URI состоящая из зарегистрированного имени или IP адреса, после которой может указываться номер порта.

Path – путь состоит из последовательности сегментов, разделённых косой чертой. Путь всегда определяется для URI, хотя может быть пустым (//).

Также в URI можно передавать параметры запроса, позволяющие модифицировать запрос с помощью пар ключ-значение, разделяемых знаком амперсанда (&). Знак вопроса (?) указывает на начало данной части URI.

Фрагмент не обязательная часть URI следующая за знаком решётки (#). Фрагмент предоставляет указатель на второй ресурс, такой как заголовок раздела в статье. Если запрашиваемый ресурс это HTML документ, то фрагмент указывает на id атрибута определённого элемента, и браузер автоматически прокручивает страницу к данному элементу.

Заголовки (Headers) хранят информацию, относящуюся как к клиенту, так и к серверу. Выглядят они как пара ключ-значение(я) разделённые двоеточием. В основном заголовки предоставляют информацию о теле запроса и ответа, данные аутентификации, кэшировании и куках.

Тело (Body) используется для передачи на сервер дополнительной информации. Например, это может быть фрагмент данных, который вы хотите добавить или заменить. Тело запроса отсутствует в методах чтения, таких как GET, HEAD.

Стуктура ответа

Ответ(response) состоит из кода ответа (status code), заголовков и тела.

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

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

HTTP/1.1 200 OK
Date: Wed, 28 Apr 2021 17:37:01 GMT
Content-Type: text/html
 
<!DOCTYPE html>
<html>
   <head>
       <title>Home Page</title>
   </head>
   <body>
       <div>Hello World!</div>
       <a href="http://www.recurse.com">Check out the Recurse Center!</a>
       <img src="awesome-pic.jpg"/>
   </body>
</html>

Также в ответе мы видим статус код отправленный сервером - 200 ОК. В данном примере он говорит об успешно выполненной операции. Статус коды делятся на 5 категорий: информационные, успешные, перенаправления, ошибка клиента и ошибка сервера. Подробнее о статус кодах поговорим в следующих статьях.

На этом на сегодня всё, stay tuned! :D                                                   

Источники информации:

What is SOAP: Formats, Protocols, Message Structure, and How SOAP is Different from REST, REST API: Key Concepts, Best Practices, and Benefits и Wikipedia )