Мы ежедневно пользуемся приложениями на телефоне, работаем в интернете через браузер, совершаем покупки с использованием банковских карт и совершаем еще множество действий с использованием электронных гаджетов, которые общаются между собой посредством API.
В этой статье мы разберемся в том, что такое API, как оно работает, какие дает преимущества и каких типов бывает. Подробнее остановимся на REST API, рассмотрим его возможности, а также, конечно же, попрактикуемся в вызове HTTP-запросов на примере 1cloud API.
Что такое API?
Говоря простыми словами, API — это набор договоренностей, благодаря которым программы могут общаться между собой, обмениваться информацией. API описывает протокол передачи данных, формат данных и непосредственно модель самих данных. Это нужно для того, чтобы программы вели себя соответствующе заданному «контракту» и обменивались только теми данными, которые описаны в контракте.
Чаще всего вы встретите определение API как Application Programming Interface — программный интерфейс приложения. Приложением может быть любое ПО или программа, которая что-то принимает на вход для обработки данных и что-то возвращает после обработки. Такая схема очень похожа на взаимодействие логико-структурных элементов ЯП: классы, методы, функции, переменные.
Например, в Python, это может выглядеть так:
from functools import reduce
def quader(*args: int) -> int:
"""
Функция принимает на вход любое количество аргументов, перемножает их между собой, возводит в квадрат и возвращает результат в виде целочисленного числа.
"""
return reduce(lambda x, y: x * y, map(lambda x: x * x, args))
def fibonachi(n: int) -> list:
"""
Функция принимает на вход целочисленное число и строит ряд Фибоначчи, длиной равной переданному аргументу в функцию.
"""
fib_sequence = [0, 1]
for i in range(2, n):
fib_sequence.append(fib_sequence[-1] + fib_sequence[-2])
return fib_sequence[:n]
print(fibonachi(quader(2,2)))
Как видно из примера мы создали две функции, а затем передали одну функцию в качестве аргумента другой функции и распечатали результат. Такое возможно благодаря внутреннему API Python. Обычно API реализует клиент-серверную модель. Это когда есть программа, которая располагается где-то на VPS/сервере/облаке, а к ней подключаются клиенты и она возвращает им какие-то данные в зависимости от их запроса. По такой схеме работают многие мобильные приложения, сайты и БД.
Например, подключение к СУБД SQL и работа с ней происходит по-стандартизированному API, который определяет SQL-команды и данные, которые будут возвращены. Другой интересный пример работы API — это Google- и Yandex-карты, которые используются в их сервисах. К примеру, приложение Yandex GO (Такси) использует сразу множество API:
- для определения местоположения используется API андроида для запроса к GPS;
- для отображения карты используется API Yandex Карт;
- для оплаты используется API эквайринга.
API — это интерфейс, своего рода связующее звено или граница между двумя системами, которые общаются друг с другом, при этом API ничего не знает о том, что происходит внутри каждой из систем. Такой подход обеспечивает гибкость и независимость в разработке. Мы просто что-то отправляем по API в систему, а она нам возвращает результат и нам не нужно знать, как это всё работает под капотом.
Благодаря такому подходу разработчики и пользователи получили удобные инструменты разработки и взаимодействия с целыми системами. Например, ОС предоставляет API для работы программ с ресурсами компьютера. Так программы могут получать доступ к видеокарте для отрисовки графики, или получать доступ к устройствам ввода для взаимодействия с интерфейсом программы.
Как мы говорили ранее, API определяет не только какая информация и в каком формате будет передана, но и как эту информацию нужно передать. Всего есть 4 общепринятых типа построения API:
- SOAP (Simple Object Access Protocol) — это протокол для обмена структурированными сообщениями между веб-сервисами. Он использует формат данных XML для кодирования сообщений. SOAP применяется в распределенных системах и веб-сервисах для взаимодействия между клиентами и серверами. Сегодня SOAP встречается не так часто, так как XML довольно громоздкий, а сама архитектура SOAP не гибкая.
- RPC (Remote Procedure Call) API — это метод взаимодействия между компонентами распределенной системы, позволяющий вызывать функции на удаленном сервере, как будто они являются локальными. Формат данных в RPC может быть разным, включая XML, JSON и бинарные форматы. RPC API применяется в распределенных системах для обеспечения совместной работы между клиентами и серверами с минимальными задержками.
- WebSocket API — это двунаправленный протокол связи, позволяющий установить постоянное соединение между клиентом и сервером для обмена данными в режиме реального времени. Формат данных в WebSocket может быть текстовым или бинарным, включая JSON, XML и другие. WebSocket API часто используется в веб-приложениях для обмена сообщениями между сервером и браузером пользователя, например, в онлайн-играх, чатах или приложениях для обмена данными в реальном времени.
- REST (Representational State Transfer) API — это архитектурный стиль для разработки веб-сервисов, основанный на стандартных HTTP-методах и ресурсоориентированном подходе. Формат данных в REST API может быть разнообразным, включая JSON, XML и другие. REST API широко применяется в веб-приложениях и мобильных приложениях для обеспечения межсистемного взаимодействия и интеграции с различными сервисами и платформами.
Наибольшее распространение получил REST формат API, так как он наиболее прост для разработки и понятен для пользователей. Именно о REST мы и будем говорить далее.
Что такое REST API?
REST (Representational State Transfer) API работает поверх HTTP(S)-протокола и максимально эффективно использует его свойства. Можно сказать, что REST — это не какой-то стандарт, а архитектурный стиль написания запросов. Часто ещё его называют RESTful API. А вот HTTP (HyperText Transfer Protocol) — это протокол передачи данных, используемый во всемирной паутине для обмена информацией между клиентами и серверами.
HTTP определяет методы запроса к ресурсу, которые используются для выполнения разных операций:
- GET-запрос используется для получения информации от сервера. Он запрашивает данные от определенного ресурса и не вносит изменения на сервере. Примером может быть просмотр веб-страницы или получение данных из API.
- PUT-запрос используется для обновления существующих данных на сервере. Он требует передачи полного обновленного набора данных для указанного ресурса. Если ресурс не существует, сервер может создать его, в зависимости от реализации.
- DELETE-запрос используется для удаления указанного ресурса на сервере. Он не требует передачи дополнительных данных.
- POST-запрос используется для создания нового ресурса на сервере. Он передает данные, которые должны быть использованы для создания нового ресурса. В отличие от PUT-запроса, POST-запрос не требует знания о существующих ресурсах и их идентификаторах.
HTTP-запрос определяется HTTP-методом и может содержать различные заголовки и информацию в виде JSON-данных для обработки. Вот так может выглядеть схема работы HTTP-запроса к 1cloud API для получения баланса проекта:
Как видно из схемы клиент отправляет запрос на определенный URI, с указанием конкретного метода запроса и заголовками. В нашем случае, мы послали GET-запрос на URI: https://api.1cloud.ru/customer/balance с заголовком Authorization и значением Bearer … — многоточие указывает на API-ключ, который обязательно указывается при любых API-запросах к 1cloud API.
В ответ API-сервер 1cloud нам возвращает список значений. Об этом свидетельствуют квадратные скобки. В зависимости от запроса, API-сервер может возвращать различной сложности JSON-данные. Например, при запросе списка серверов, в ответ мы получим JSON следующего вида:
[
{
"ID":777,
"Name":"test2API",
...
"LinkedNetworks": [
{
"LinkID": 139856,
"NetworkID": 274,
..
},
{
"LinkID": 154883,
"NetworkID": 1362,
..
}
],
"DCLocation":"SdnSpb",
"ImageFamily":"Windows",
"LinkedSshKeys": []
}
...
]
JSON является общепринятым форматом передачи данных в REST API, так как его легко конвертировать в любой другой формат и с ним работают все ЯП.
Еще одной важной отличительной чертой REST является то, что REST API не хранят состояния. Это означает, что при каждом обращении к ресурсу через определенную конечную точку (endpoint), API предоставляет идентичный ответ, не учитывая предыдущие запросы, которые не влияют на последующие результаты.
Хорошо, у нас уже есть общее представление о том, что такое API и REST API. Настало время углубиться и разобраться детальнее в том, как оно работает.
Разверните виртуальный сервер и протестируйте REST API
Закажите облачный сервер с произвольной конфигурацией в Панели 1cloud. За несколько минут вы можете развернуть целый парк виртуальных серверов и объединить их в изолированные виртуальные сети.
Работа REST API на примере 1cloud API
Рассмотрим работу REST API на примере реализации 1cloud API. Как мы уже говорили ранее, одно из ключевых понятий REST API — это ресурс. Ресурсы связаны с определенными URI, а те в свою очередь связаны с HTTP-методами запроса.
1cloud — это облачный провайдер, который предоставляет такие ресурсы как виртуальные серверы на базе Enterprise и Open Source виртуализаций, виртуальные ЦОДЫ, S3-хранилища, DNS-хостинг, мониторинг и многие другие услуги, некоторые из которых имеют управление по API. Например, виртуальные серверы.
Для управления виртуальными серверами 1cloud нужно посылать определенные HTTP-запросы на нужные URL. Структура URL и запросов следующая:
| URL | HTTP-запрос | Действие | Ответ |
|---|---|---|---|
| https://api.1cloud.ru/server/ | GET | Запросить список созданных серверов. | JSON со списком созданных серверов. |
| POST | Создать виртуальный сервер. | JSON со статусом создания виртуального сервера. | |
| https://api.1cloud.ru/server/{id} | DELETE | Удаление виртуального сервера по id. | Текст со статусом «OK». |
| PUT | Изменение конфигурации виртуального сервера по id. | JSON со статусом задачи и выходными параметрами измененного сервера. | |
| https://api.1cloud.ru/server/{id}/action | POST | Выполнение действий над сервером: вкл./выкл. сервер по питанию и средствами OS, перезагрузить сервер по питанию или средствами OS. | JSON со статусом задачи. |
| https://api.1cloud.ru/server/{id}/action | GET | Получить список действий над сервером. | JSON со списком действий над сервером. |
Использование HTTP-методов, как правило, подразумевает передачу дополнительных заголовков и данных для обработки на сервере. В случае с 1cloud API в качестве дополнительного заголовка передается:
- Тип данных, которые отправляются или принимаются от сервера — Content-Type: application/json;
- API-ключ для авторизации — Authorization: Bearer XXX…
В теле сообщения, в JSON-формате передаются данные необходимые для выполнения определенных действий. Так заголовок авторизации с API-ключем передается всегда: 'Authorization: Bearer XXX..', а вот данные в теле запроса, указываются только для PUT и POST запросов.
Получить API-ключ для авторизации можно в Панели управления 1cloud, в разделе «Настройки» -> «Настройки профиля» -> «API-ключ»:
Отправить HTTP-запрос можно множеством инструментов: начиная от исполняемых скриптов, заканчивая специальными программами. Например, postman или curl. Работать с 1cloud API через Python мы будем в следующей статье, а сейчас посмотрим, как это всё работает через cURL и Postman.
Вот как будет выглядеть HTTP-запрос на получение списка виртуальных серверов 1cloud:
| cURL | Postman |
|---|---|
| curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX…' "https://api.1cloud.ru/server" | GET /server HTTP/1.1 Host: api.1cloud.ru Content-Type: application/json Authorization: Bearer XXX… |
В ответ мы получим JSON со списком серверов следующего типа (некоторые поля удалены для сокращения длины сообщения):
[
{
"ID": 945993,
"Name": "Server",
"State": "Active",
"IsPowerOn": true,
"CPU": 2,
"RAM": 2048,
"HDD": 40,
"IP": "188.227.17.34",
"Image": "Ubuntu18.04x64",
"IsHighPerformance": false,
"HDDType": "SSD",
"PrimaryNetworkIp": "188.227.17.34",
"LinkedNetworks": [],
"DCLocation": "SdnSpb",
"LinkedSshKeys": [],
"DateCreate": "2023-04-26T14:25:38.867"
}
]
Хорошо, с GET запросами всё просто, куда интереснее дела обстоят с PUT и POST запросами. Вместе с заголовками нам нужно передать еще и тело сообщения (body) с определенными ключами и значениями, которые строго определены в документации к 1cloud API.
Вот пример HTTP-запроса на создание сервера в ЦОДе Xelent:
| cURL | Postman |
|---|---|
| curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX…' "https://api.1cloud.ru/server" -d '{ "Name": "testapi1", "CPU":2, "RAM":2048, "HDD":40, "ImageID": "3", "HDDType":"SSD", "DCLocation":"SdnSpb", "isHighPerfomance":"false"'} | POST /server HTTP/1.1 Host: api.1cloud.ru Content-Type: application/json Authorization: Bearer XXX… {"Name": "PM_test_api", "CPU":2, "RAM":2048, "HDD":40, "ImageID": "3", "HDDType":"SSD", "DCLocation":"SdnSpb", "isHighPerfomance":"false"} |
В ответ мы получим JSON с параметрами созданного сервера:
{
"ID": 947517,
"Name": "testapi1",
"HostName": null,
"State": "New",
"IsPowerOn": false,
"CPU": 2,
"RAM": 2048,
"HDD": 40,
"IP": "",
"AdminUserName": null,
"AdminPassword": null,
"Image": "WinServer2012R2x64En",
"IsHighPerformance": false,
"HDDType": "SSD",
"PrimaryNetworkIp": "",
"LinkedNetworks": [],
"DCLocation": "SdnSpb",
"ImageFamily": "Windows",
"LinkedSshKeys": [],
"DateCreate": "2023-04-27T11:56:15.1221137+03:00"
}
Эти данные пока не очень полезны (кроме ID-сервера), так как не содержат данные для подключения. Для получения этой информации после создания сервера нужно отправить HTTP-запрос на получение списка серверов — там будет информация для подключения к серверам.
Если нужно удалить сервер — достаточно отправить DELETE HTTP-запрос на URL https://api.1cloud.ru/server/{id}, где id подменяется на числовое id-сервера. Например, удалить сервер 945993 можно так:
| cURL | Postman |
|---|---|
| curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer XXX…' "https://api.1cloud.ru/server/945993" | DELETE /server/{id} HTTP/1.1 Host: api.1cloud.ru Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW Authorization: Bearer XXX… |
Итак, с помощью 1cloud API вы можете совершать множество действий с серверами и другими ресурсами облачного провайдера. Но использовать для управления ресурсами cURL или PostMan — это не самый удобный путь. В следующей статье мы покажем как можно использовать 1cloud API более эффективно с помощью Python, а пока подведем итог.
Кратко о API и REST API
API — это набор договоренностей и правил между программами для обмена данными. API предоставляет интерфейс для общения программ, при этом ему ничего не нужно знать о том, что происходит внутри взаимодействующих элементов. API работают поверх различных протоколов. Например, REST API работает поверх HTTP-протокола.
REST API или RESTful API — это стиль написания API-запросов, который использует стандартные HTTP-методы для работы. Часто при работе с REST используют понятие CRUD-модели, каждому элементу из которых соответствует свой HTTP-метод:
- С — create (POST);
- R — read (GET);
- U — update (PUT);
- D — delete (DELETE).
Главной отличительной особенностью REST API является то, что он направлен на использование ресурсов, то есть у каждого ресурса есть свой URL, с которым мы можем взаимодействовать с помощью HTTP-методов. Обычно API URL имеют такой вид: базовый URI + URI ресурса. Хорошим примером является URL 1cloud API: базовый URI — https://api.1cloud.ru/ + URI ресурса — /server/, /dns/, /monitoring/.
Работать с REST API можно как с помощью специализированных программ: cURL, PostMan, так и с помощью различный ЯП библиотек:
- Go:
- net/http: Встроенный пакет для работы с HTTP, включая отправку и получение HTTP-запросов.
- resty: Простая и легкая библиотека для выполнения HTTP-запросов с функциями, такими как автоматическое повторение запросов и поддержка таймаутов.
- Rust:
- reqwest: Асинхронная библиотека для выполнения HTTP-запросов с поддержкой множества функций, таких как JSON, отправка форм и пр.
- hyper: Низкоуровневый, асинхронный клиент и сервер HTTP, позволяющий создавать кастомные HTTP-запросы и обработчики.
- C++:
- libcurl: Многофункциональная библиотека для работы с URL, включая поддержку HTTP, HTTPS и других протоколов.
- cpprestsdk (C++ REST SDK, также известная как Casablanca): Библиотека для создания клиентов и серверов REST на C++.
- C#:
- HttpClient: Встроенный класс в .NET Framework и .NET Core для отправки HTTP-запросов и получения HTTP-ответов от REST API.
- RestSharp: Простая и популярная библиотека для работы с HTTP и RESTful веб-сервисами в C#.
- Python:
- http.client (Python 3) / httplib (Python 2): Встроенная библиотека для работы с HTTP, предоставляющая классы для реализации HTTP-клиентов.
- urllib: Встроенная библиотека для работы с URL, включая отправку HTTP-запросов. В Python 3, эта библиотека разделена на две части - urllib.request и urllib.parse.
- aiohttp: Асинхронная библиотека для выполнения HTTP-запросов, основанная на asyncio и применяющаяся в асинхронных приложениях Python.
- treq: Библиотека для работы с HTTP, основанная на Twisted и предоставляющая аналогичный requests интерфейс, но в асинхронном контексте.
- httpx: Полнофункциональный асинхронный клиент HTTP для Python 3, предоставляющий поддержку HTTP/1.1 и HTTP/2.
В следующей статье мы рассмотрим примеры работы с 1cloud API через Python, с использованием стандартной библиотеки Python — requests.