Table of Contents
API теория
Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений или программный интерфейс приложения). Технология API это описание способов (набор классов, процедур, функций, структур и констант), которыми одна компьютерная программа может взаимодействовать с другой программой.
Углубляться в теорию мы не будем. Нас интересует только понятие API Вызовов в WEB среде, с которыми мы будем работать.
Простыми словами, API Вызовы это запросы, которые имеют вид ссылки (иногда называются Роуты), и передаются на определенный хост, для получения или отправки информации. API вызовы могут содержать дополнительные параметры, для уточнения полученной выборки или отправляемой информации.
Также нужно знать что стандартными методами для HTTP протокола (по которому мы отправляем запросы) являются — GET (запросить), PUT(заменить или обновить), DELETE(удалить), POST(отправить).
НО, эти методы таким способом только для HTTP протокола. И соотвественно для API, которое реализованно с помощью подхода который базируется на HTTP протоколе.
Тоесть возможна реализация API на базе только метода POST, который будет и отправлять и получать и удалять информацию.
Типами данных которые мы передаем в теле запроса являются (Подробнее читать тут):
- Text — application/x-www-form-urlencoded
- text/plain — application/json
- text/xml — application/javascript
- text/html — application/xml
- multipart/form-data
- application/x-www-form-urlencoded
- application/json
- application/javascript
- application/xml
Основные подходы к реализации WEB API
Важно понимать что технология API имеет множество подходов к реализации, и каждый из них имеет свои стандарты.
Рассмотрим три основных подхода:
- Простой протокол доступа к объектам SOAP (Simple Object Access Protocol);
- Передача состояния представления REST (Representational State Transfer) ;
- Удаленный вызов процедур JSON-RPC (Remote Procedure Call).
SOAP
Некоторые разработчики могут не согласиться с тем, что SOAP «прост», потому что, для выполнения вызовов необходимо использовать формат XML. Данный формат не совсем интуитивно понятен, что не только затрудняет реализацию вызовов, но и затрудняет отладку.
С другой стороны, SOAP использует как транспортные, стандартные протоколы (например HTTP).
REST
Базируется на транспортном протоколе HTTP для обмена информацией между различными приложениями или службами. REST более гибок, чем SOAP в том смысле, что поддерживает различные форматы данных, а не требует XML,(к примеру JSON).
REST API также может предложить лучшую производительность, чем SOAP, поскольку он может кэшировать данные.
JSON-RPC
По сравнению с REST и SOAP JSON-RPC относительно узок по возможностям. Он поддерживает исключительно небольшой набор команд и не обеспечивает такой гибкости, как REST, он поддерживает только один формат передачи данных — JSON.
Зато данный подход не базируется на стандартных протоколах, а только использует их как транспортные. Можно сказать что JSON-RPC независим от протоколов.
Небольшое сравнение:
SOAP | REST | JSON-RPC | |
Поддерживает форматы | XML | JSON, XML. e.t.c | JSON |
Данные запроса могут быть: | В URI запроса В GET параметрах В HTTP заголовках |
В URI запроса В GET параметрах В HTTP заголовках |
В теле запроса |
Данные ответа могут быть: | В HTTP коде ответа В HTTP заголовках В теле ответа (формат не стандартизирован) |
В HTTP коде ответа В HTTP заголовках В теле ответа (формат не стандартизирован) |
В теле ответа (формат стандартизирован) |
Примеры API (Использование в WEB)
Для примера мы будем использовать сервис Новой Почты и SendPuls.
API NovaPoshta- ссылка
API SendPuls — ссылка
Для начала рассмотрим пример с SendPuls.
Вот Наша ссылка на сервер API запросов: https://api.sendpulse.com/
Возьмем POST запрос на авторизацию — oauth/access_token
Формат передачи данных: application/x-www-form-urlencoded
Параметры запроса:
Parameter | Value |
grant_type* | client_credentials |
client_id* | YOUR ID |
client_secret* | YOUR SECRET |
Этот POST запрос передается в формате Form-Data и будет иметь структуру:
POST https://api.sendpulse.com/oauth/access_token HTTP/1.1
Host: api.sendpulse.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 77
grant_type=client_credentials&client_id=[YOURID]&client_secret=[YOUR SECRET]
Теперь рассмотрим пример с Новой Почты
Вот Наша ссылка на сервер API запросов: https://api.novaposhta.ua/v2.0/json/
Возьмем простой POST запрос на получение списка городов — Address/searchSettlements
Тип передачи данных — application/json
Параметры запроса:
Parameter | Data type | Value |
apiKey* | string[36] | YOUR API KEY |
modelName* | string | Address |
calledMethod* | string | searchSettlements |
CityName* | string[36] | Львів |
Limit* | int[36] | 5 |
Таким образом наш POST запрос в формате JSON, будет иметь структуру:
POST http://api.novaposhta.ua/v2.0/json/Address/searchSettlements/ HTTP/1.1
Host: api.novaposhta.ua
Content-Type: application/json
{
"apiKey": "[YOUR API KEY]",
"modelName": "Address",
"calledMethod": "searchSettlements",
"methodProperties": {
"CityName": "Львів",
"Limit": 5
}
}
Что такое Postman и для чего он нужен
Как Вы убедились ранее, для отправки API вызовов нужны знания синтаксиса языка программирования, на котором вы собираетесь отправляется запрос, и кроме этого нужна среда, в которой вы сможете написать и отправить данный запрос.
Тут нам на помощь приходит приложение Postman.
Postman это десктоп приложение, (существует и в виде расширения для Google Chrome), которое содержит набор инструментов для тестирования API. Это приложение позволяет выполнять API вызовы с помощью визуального интерфейса, без использования кода, а также выполнять авто проверку ответа.
Для чего и кому он нужен?
Postman нужен тестировщиком для прогона позитивных тест кейсов связанных с API, в ходе дымового, модульного тестирования или регрессионного тестирования.
Postman также подходит и для разработчиков для того чтобы составить API модель приложения и проверять реализованные роуты.
Какие возможности приложения:
- Создание Коллекций и шаринг коллекций;
- Построение иерархий Папок внутри одной коллекции;
- Создание Запросов, и настройка их параметров;
- Написание Скриптов, которые могут выполнятся перед запросом и после него;
- Настройка Окружения;
- Использование переменных;
- Запуск коллекции;
- Работа в консоли.
Интерфейс Postman
Итак рассмотри интерфейс приложения и основные его элементы.
- Меню Коллекций;
- Вложенные в коллекцию папки;
- Запросы;
- Конструктор запросов:
- URL и метод;
- Параметры запроса;
- Параметры ответа;
- Меню окружения и переменных;
- Запуск коллекции;
- Консоль.
Далее Вы можете использовать мою презентацию для рассмотрения всего функционала более детально. Функционал создания папок и Коллекций, а так же создание запросов был показан в ходе демонстрации, и не присутсвует в презентации, эту информацию Вы сможете взять в учебном центре Postman.
Выступление с данной презентацией происходило в компании GalobalLogic 03.07.2019. Размещено с разрешения сотрудников компании.