Руководство для начинающих по работе с API

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

В прошлый раз мы сделали следующий запрос:

# Defining method (X), and headers (H):
cURL -X GET 'https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY' -H 'Host: api.nasa.gov' -H 'Accept: text/html,application/xhtml+xml,application/xml'

# Or, alternatively can also be written verbose

# Using long form options
# Splitting cURL commands across multiple lines
# Line continuation character is represented in cURL by ``

cURL 
--request GET 'https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY' 
--header 'Host: api.nasa.gov' 
--header 'Accept: text/html,application/xhtml+xml,application/xml'
Войти в полноэкранный режим Выйти из полноэкранного режима

Обратите внимание, что приведенный выше код не является JavaScript, и он выглядит иначе, чем код из нашего предыдущего примера. Он начинается с cURL (для клиентского URL), который представляет собой инструмент командной строки, используемый разработчиками для передачи данных.

В итоге, ознакомьтесь с cURL. На самом фундаментальном уровне cURL позволяет вам (а) разговаривать с сервером, (б) поддерживает несколько различных протоколов и (в) работает на различных платформах. Все это делает cURL идеальным для тестирования связи из любого места, где есть доступ к командной строке и сетевому соединению. Подробнее о том, что делает cURL, здесь, а о документации cURL — здесь.

Инструментарий cURL

Какие инструменты мы можем использовать для тестирования различных веб-сервисов перед созданием API-интеграций? Я рекомендую следующие инструменты, которые мы будем использовать сегодня:

  • Postman: для тестирования веб-сервисов и генерации cURL сниппетов (и для нескольких других языков).
  • cURL Converter (опционально): для преобразования команд cURL в JavaScript (и для некоторых других языков).

Итак, в этот раз давайте начнем использовать cURL для представления вызовов API, с которыми мы будем работать с помощью Postman (платформа для создания и использования API).

Использование Postman

Отправка первого запроса

Postman позволяет легко создавать и отправлять API-запросы. Вам не нужно вводить команды в терминале или писать какой-либо код. В его графическом интерфейсе достаточно просто создать новый запрос (например, используя данные из фрагмента cURL) и нажать кнопку Send. Ответ API появляется прямо внутри Postman.

Если вы никогда раньше не пользовались Postman, давайте сделаем это шаг за шагом.

Как войти в Postman:

  1. Войдите с помощью Google (или электронной почты/имени пользователя) в Postman
  2. Заполните информацию о пользователе (имя и роль, John Doe, Fullstack Developer).
  3. Продолжить без команды

Создание HTTP-запроса с помощью cURL и Postman

Итак, давайте возьмем наш фрагмент cURL и импортируем его в Postman. Чтобы сделать это:

  1. В личном рабочем пространстве нажмите на иконку + New HTTP Request, чтобы сразу же отправить запрос. В качестве альтернативы, используйте инструмент Импорт и вставьте фрагмент cURL, представленный выше, чтобы сэкономить время,
  2. Если вы импортируете (если нет, пропустите этот шаг), появится модальное/всплывающее окно, в котором вы импортируете спецификации API как Raw Text, нажмите Continue и подтвердите, нажав Import.
  3. Нажмите на Отправить и
  4. Просмотрите ответ прямо в Postman.

Примечание: Импорт API — это отличная функция, позволяющая импортировать существующую схему API из локального файла, каталога, URL, необработанного текста, хранилища кода или даже API-шлюза. Это полезно знать, поскольку Postman позволяет импортировать и экспортировать данные, чтобы помочь вам консолидировать рабочий процесс разработки API.

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

Методы HTTP-запросов

Как мы уже говорили, архитектурный стиль REST использует все преимущества HTTP, поэтому, в свою очередь, любой RESTful API также унаследует их. На самом базовом уровне запрос API включает в себя URL конечной точки ресурса и метод запроса HTTP. Метод запроса HTTP (также называемый HTTP-глаголами) указывает на желаемое действие, которое вы хотите выполнить для данного ресурса.

Все методы HTTP-запросов имеют общие черты: они безопасны, идемпотентны и кэшируемы. Рассмотрим наиболее распространенные методы:

  • GET извлекает данные из API
  • POST отправляет новые данные в API
  • PATCH и PUT обновляют существующие данные
  • DELETE удаляет существующие данные

Давайте изучим эти методы HTTP с помощью нашей первой коллекции Postman.

Коллекции Postman

Это группа сохраненных запросов. Чем больше вы используете Postman, тем больше времени отнимает необходимость оставлять открытыми вкладки для запросов, искать их в разделе истории или создавать их заново. Вместо этого вы можете сохранить все свои запросы, упорядочить их и поделиться ими в виде коллекции Postman.

Вы можете создать коллекцию следующим образом:

  • Сохранив один запрос и воспользовавшись быстрой ссылкой Новая коллекция во всплывающем окне/модальном меню ИЛИ
  • нажав на значок + на вкладке Обзор (левое меню) вашего рабочего пространства.

Теперь, когда вы знаете, как создать коллекцию Postman, давайте быстро обсудим, как поделиться результатами работы Postman.

Экспорт данных Postman

Вы можете экспортировать свои коллекции Postman в файлы JSON для последующего использования из любого экземпляра Postman или использовать их с помощью инструмента CLI, например, Newman (инструмент, позволяющий запускать коллекции Postman из командной строки). Нажмите на Export или Share в любом месте папки с коллекцией. Отсюда у вас есть следующие возможности:

  • Отправить коллекцию по электронной почте для совместной работы (аналогично предыдущему варианту экспорта).
  • Экспорт в виде файла JSON
  • Через JSON ссылку, которая генерирует статический снимок вашей коллекции (подобно тому, что я предоставил ранее).

Заключение

Postman имеет более 135 тысяч опубликованных коллекций, которые вы можете использовать для изучения нескольких различных API. Компании активно используют Postman не только для разработки и тестирования своих API, но и для быстрого создания прочной базы документации и предоставления ее миру. Для всех публичных коллекций Postman существуют категории AI, Communication, Data Analytics, Developer Productivity, DevOps, Financial Services, поэтому обязательно ознакомьтесь с ними и продолжайте учиться работать с API.

ПРИМЕЧАНИЕ: Эта статья относится к продолжающемуся циклу статей, который все еще находится в процессе работы. Если вы еще не читали, ознакомьтесь с частью 1: Введение в API. Часть 3: Руководство для начинающих по тестированию API.

Спасибо за прочтение.

Оцените статью
Procodings.ru
Добавить комментарий