• API расшифровывается как интерфейс прикладного программирования.
• API-интерфейсы позволяют взаимодействовать с программным обеспечением или платформами без необходимости разбираться в их внутреннем коде или структуре базы данных.
• Существуют различные модели интеграции API, такие как REST, RPC, GraphQL, Polling, WebSockets и WebHooks.
• REST API являются самой простой и популярной формой интеграции “запрос-ответ”.
• RPC-сервер полностью зависит от действий, а не от ресурсов.
• GraphQL позволяет клиентам точно определить, какие данные им нужны, и обладает высокой степенью гибкости.
• Интеграция, управляемая событиями, идеально подходит для сервисов с быстро меняющимися данными, таких как опросы, WebSockets и WebHooks.
Введение
API расшифровывается как «интерфейс прикладного программирования». Буква «I» в аббревиатуре API — это ключевая часть, которая объясняет его назначение.
Интерфейс (interface ) - это то, что программное обеспечение предоставляет другим пользователям или программам, позволяя им взаимодействовать с ним. Хорошей аналогией интерфейса является пульт дистанционного управления. Представьте, что у вас есть универсальный пульт, с помощью которого можно управлять телевизором, светом и вентилятором.
Давайте разберем, что может делать универсальный пульт дистанционного управления:
На пульте дистанционного управления есть несколько кнопок, каждая из которых служит для определённой цели. Одна кнопка может переключать каналы, другая может приглушить свет люстры, а третья может включить вентилятор.
Когда вы нажимаете кнопку, она отправляет определённый сигнал через инфракрасный порт, Bluetooth или Wi-Fi на объект, которым вы управляете, и даёт ему команду выполнить определённое действие.
Главное в пульте дистанционного управления то, что он позволяет взаимодействовать с телевизором, люстрой и вентилятором, не разбираясь во внутреннем устройстве этих объектов. Все эти сложности скрыты от вас. Вы просто нажимаете кнопку и получаете ответную реакцию, которую можете сразу же увидеть.
API-интерфейсы работают аналогичным образом.
API могут иметь различные конечные точки, каждая из которых предназначена для выполнения определённого действия. Одна конечная точка может получать данные, а другая — обновлять или удалять их.
Когда вы отправляете запрос на конечную точку, он взаимодействует с сервером с помощью методов HTTP — GET, POST, PUT, DELETE, чтобы выполнить определённое действие (например, получить, отправить, обновить или удалить данные).
Ключевая особенность API, как и в случае с пультами дистанционного управления, заключается в том, что API абстрагируют внутреннюю работу сервера и базы данных, лежащих в основе API. Это позволяет пользователям, разработчикам и приложениям взаимодействовать с программным приложением или платформой, не разбираясь в их внутреннем коде или структуре базы данных. Вы просто отправляете запрос, сервер обрабатывает его и предоставляет ответ.
Эта аналогия справедлива лишь до тех пор, пока API не стали сложнее, чем пульт дистанционного управления. Но основные принципы работы API и универсального пульта дистанционного управления довольно схожи.
В этой статье мы рассмотрим шаблоны интеграции API, которые можно разделить на две большие группы: API с запросом-ответом (REST, RPC и GraphQL) и API, управляемые событиями (Polling - опрос, WebSockets и WebHooks).
Интеграция запросов и ответов (Request-Response Integration)
При интеграции по принципу «запрос-ответ» клиент инициирует действие, отправляя запрос на сервер, а затем ожидает ответа. Существуют различные модели интеграции по принципу «запрос-ответ», но на высоком уровне все они подчиняются одному и тому же правилу: клиент инициирует запрос и ожидает ответа от сервера.
1. REST
REST расшифровывается как Representational State Transfer — аббревиатура представляет собой сочетание первых букв этих трёх слов. Это самая простая и популярная форма интеграции запросов и ответов.
REST-API используют модель без сохранения состояния ( stateless ), клиент-серверную модель связи, при которой каждое сообщение содержит всю информацию, необходимую для понимания и обработки сообщения. REST — это всё о ресурсах. Ресурсы — это сущности, предоставляемые API, к которым можно получить доступ и которыми можно управлять с помощью URL-адресов.
Чтобы понять, как работают REST API, рассмотрим следующую аналогию. Представьте, что вы пришли в ресторан, чтобы заказать еду. Меню обширное, и блюда в нём распределены по категориям. Каждый пункт меню можно приравнять к ресурсу. Сначала вы обращаетесь к официанту, чтобы привлечь его внимание, а затем делаете заказ. Каждый запрос получает ответ, прежде чем вы перейдёте к следующему запросу, например, заказу блюда.
В терминах REST API клиент инициирует запросы к серверу, указывая, что именно он хочет получить, с помощью методов HTTP (таких как GET, POST, PUT, DELETE) по определённым URL-адресам (пунктам меню). Каждое взаимодействие является безстадийным, то есть каждый запрос от клиента к серверу должен содержать всю информацию, необходимую для понимания и обработки запроса. Сервер обрабатывает запрос и возвращает соответствующий ответ — заказанный товар.
2. RPC
RPC расшифровывается как «вызов удаленной процедуры». В отличие от REST API, которые работают с ресурсами, RPC работает с действиями. С помощью RPC клиент выполняет блок кода на сервере.1.
Представьте себе ресторан без меню. В этом ресторане вы не можете заказать блюдо. Вместо этого вы просите ресторан выполнить определённое действие.
С помощью REST API гость мог бы просто заказать рыбу с жареной картошкой. При использовании RPC ему пришлось бы давать указания о том, что он хочет, чтобы приготовила кухня.
В шаблоне RPC клиент вызывает определённую процедуру на сервере и ожидает результата. Процедура подготовки и то, что подготавливается, тесно связаны между собой. Это может дать клиенту очень конкретные и адаптированные результаты, но не хватает гибкости и простоты использования REST.
Есть причина, по которой большинство ресторанов используют меню, а не следуют индивидуальным запросам своих клиентов. Это отчасти объясняет, почему RPC является менее популярным шаблоном интеграции по сравнению с REST.
3. GraphQL
С помощью GraphQL клиент указывает, какие именно данные ему нужны, и они могут включать в себя конкретные поля из различных ресурсов. Сервер обрабатывает этот запрос, получает нужные данные и возвращает их клиенту. Это позволяет клиенту проявлять высокую степень гибкости и получать только те данные, которые ему нужны. Кроме того, сервер должен быть способен обрабатывать более сложные и уникальные запросы.
Таким образом, GraphQL — это более настраиваемая форма REST. Вы по-прежнему работаете с ресурсами (в отличие от действий в RPC), но можете настроить способ возврата ресурса.
Представьте себе ресторан, в котором вы можете заказать собственное блюдо, указав точное количество или ингредиенты, которые вам нужны.
Это может показаться похожим на шаблон RPC, но обратите внимание, что клиент не говорит, как должна быть приготовлена еда, он просто корректирует свой заказ, убирая некоторые ингредиенты (без соли) и уменьшая количество некоторых продуктов (два куска рыбы вместо четырёх).
Одним из недостатков GraphQL является то , что он усложняет API , поскольку серверу требуется выполнять дополнительную обработку для разбора сложных запросов . Эта дополнительная сложность также применима к аналогии с рестораном, поскольку каждый заказ должен быть индивидуализирован под гостя.
У GraphQL есть одно явное преимущество перед REST и RPC. Поскольку клиенты могут точно указать, что им нужно, размер полезной нагрузки ответа обычно меньше, а значит, время ответа быстрее.
Интеграция, управляемая событиями (Event Driven Integration)
Этот шаблон интеграции идеально подходит для сервисов с быстро меняющимися данными.
Некоторые из этих шаблонов интеграции также являются асинхронными и инициируются сервером, в отличие от шаблонов запроса-ответа, которые являются синхронными и инициируются клиентом.
1. Опрос Polling
Давайте вернёмся к аналогии с рестораном. Когда вы заказываете еду, её приготовление занимает некоторое время.
Вы можете узнать о готовности вашего заказа, спросив у официанта, готов ли он. Чем чаще вы будете спрашивать, тем ближе вы будете к получению информации о вашем заказе в режиме реального времени.
Однако это создаёт ненужную нагрузку на официанта, поскольку ему приходится постоянно проверять статус вашего заказа и сообщать вам о нём, когда вы спрашиваете.
Опрос — это когда клиент постоянно запрашивает у сервера наличие новых данных с заданной частотой. Это неэффективно, потому что многие запросы могут не возвращать новых данных, тем самым излишне расходуя ресурсы. Чем чаще вы проводите опрос (делаете запросы), тем ближе клиент к общению с сервером в реальном времени.
Большинство запросов во время опроса не приносят пользы, поскольку они возвращают что-то полезное клиенту только в случае изменений на сервере.
Однако существует другая версия опроса, называемая длительным опросом. При длительном опросе официант не сразу сообщает гостю о статусе заказа. Вместо этого официант отвечает только при наличии обновления. Естественно, это работает только в том случае, если гость и официант заранее договорились, что медленный ответ официанта не означает, что официант груб и гостя игнорируют.
При длительном опросе сервер не отвечает клиенту немедленно. Он ждёт, пока что-то не изменится, прежде чем ответить.
Пока клиент и сервер договариваются о том, что сервер будет удерживать запрос клиента, а соединение между клиентом и сервером остаётся открытым, этот шаблон работает и может быть более эффективным, чем простой опрос. Однако эти два предположения для длительного опроса могут быть нереалистичными: сервер может потерять запрос клиента и/или соединение может быть разорвано.
Чтобы устранить эти ограничения, при длительном опросе процесс усложняется за счёт необходимости указывать, какой сервер содержит соединение с клиентом, которое используется для отправки данных клиенту, когда сервер готов.
Стандартный опрос, с другой стороны, может оставаться без сохранения состояния( stateless ), что делает его более отказоустойчивым и масштабируемым.
2. WebSockets
WebSockets обеспечивают постоянный двусторонний канал связи между клиентом и сервером. После установления соединения WebSocket обе стороны могут свободно общаться, что позволяет передавать данные в режиме реального времени и более эффективно расходовать ресурсы, чем при опросе.
Снова обратимся к аналогии с рестораном: гость заказывает блюдо, а затем устанавливает специальный канал связи с официантом, чтобы они могли свободно обмениваться информацией об обновлениях или изменениях в заказе до тех пор, пока блюдо не будет готово. Это означает, что официант также может инициировать общение с гостем, чего нельзя сказать о других упомянутых ранее моделях интеграции.
WebSockets похожи на длительный опрос — они оба позволяют избежать ненужных запросов при опросе, однако у WebSockets есть дополнительное преимущество — постоянное соединение между клиентом и сервером.
Веб-сокеты идеально подходят для быстрой потоковой передачи данных в реальном времени, например, в приложениях для общения в чате. Недостатком веб-сокетов является то, что постоянное соединение потребляет пропускную способность, поэтому они могут не подходить для мобильных приложений или для регионов с плохим подключением3.
3. Веб-справочники WebHooks
WebHooks позволяют серверу уведомлять клиента о появлении новых данных. Клиент регистрирует URL-адрес обратного вызова на сервере, и сервер отправляет сообщение на этот URL-адрес, когда есть данные для отправки.
С помощью WebHooks клиент отправляет запросы как обычно, но также может прослушивать и получать запросы как сервер.
Если использовать аналогию с рестораном, то, когда гость заказывает блюдо, он даёт официанту колокольчик (аналогично URL-адресу обратного вызова). Официант идёт на кухню и звонит в колокольчик, как только блюдо готово. Это позволяет клиенту в режиме реального времени узнавать о ходе выполнения заказа.
WebHooks лучше, чем опрос, потому что вы получаете обновления от сервера в режиме реального времени, как только что-то меняется, без необходимости часто отправлять на сервер бесполезные запросы об этих изменениях. Это также лучше, чем длительный опрос, потому что длительный опрос может потреблять больше ресурсов клиента и сервера, так как предполагает поддержание открытых соединений, что потенциально приводит к большому количеству открытых соединений.
Объединяем их
В заключение отметим, что API являются важнейшими инструментами в разработке программного обеспечения, позволяя пользователям и приложениям взаимодействовать с программным обеспечением, не понимая его внутреннего устройства.
Они представлены в различных шаблонах интеграции, таких как REST, RPC, GraphQL, опрос, WebSockets и WebHooks.
Если вам нужна простая интеграция запроса и ответа, то REST, RPC или GraphQL могут быть идеальными. Для приложений реального или почти реального времени идеально подходят опросы polling, веб-кокетки WebScokets или веб-хуки WebHooks.
Как и в случае с любой другой проблемой проектирования, правильный выбор зависит от бизнес-кейса и от того, с какими компромиссами вы готовы смириться.