Как сделать запрос к api

Про API запросы и статусы. Для начинающих тестировщиков. 2023 IT

API-запросы представляют собой отправку запросов на сервер по определенным эндпоинтам с использованием различных методов HTTP, таких как GET, POST, PUT, DELETE и других. Тестирование API является одной из важных тем для проверки качества работы ПО.

Далее вы узнаете про основы:

• Про API запросы
• HTTP статусы

API запросы.

API запросы могут быть разных типов в зависимости от выполняемого действия и используемого метода. Вот некоторые из наиболее распространенных типов API запросов:

1.) GET: Запрос на получение данных из сервера. Он используется для извлечения информации из ресурса без его изменения.

Получение списка всех пользователей:

GET /api/users

Получение информации о конкретном пользователе:

GET /api/users/

2.) POST: Запрос на создание нового ресурса на сервере. Он используется для отправки данных на сервер для создания нового объекта или выполнения какого-либо действия.

Создание нового пользователя:

POST /api/users Content-Type: application/json < "name": "John Doe", "email": "[email protected]", "age": 25 >

Создание нового заказа:

POST /api/orders Content-Type: application/json < "product": "iPhone", "quantity": 2, "customer_id": "12345" >

3.) PUT: Запрос на обновление существующего ресурса на сервере. Он используется для изменения информации или состояния существующего ресурса.

Обновление информации о пользователе:

PUT /api/users/ Content-Type: application/json < "name": "Jane Smith", "email": "[email protected]", "age": 30 >

Обновление информации о заказе:

PUT /api/orders/ Content-Type: application/json

4.) DELETE: Запрос на удаление существующего ресурса на сервере. Он используется для удаления ресурса по его идентификатору или другому уникальному идентификатору.

DELETE /api/users/
DELETE /api/orders/

5.) PATCH: Запрос на частичное обновление существующего ресурса на сервере. Он используется для изменения только некоторых полей или атрибутов ресурса, не затрагивая остальные.

Частичное обновление информации о заказе:

PATCH /api/orders/ Content-Type: application/json

Частичное обновление информации о пользователе:

PATCH /api/users/ Content-Type: application/json < "email": "[email protected]" >
HTTP статусы.

HTTP статусы являются важной частью коммуникации между клиентом и сервером в API. Они предоставляют информацию о результате выполнения запроса и помогают клиентскому приложению принять соответствующие действия. Вот некоторые распространенные примеры использования HTTP статусов в API:

• 200 OK: Запрос успешно выполнен. В ответе содержится запрашиваемая информация.
• 201 Created: Запрос успешно выполнен, и в результате был создан новый ресурс.
• 204 No Content: Запрос успешно выполнен, но в ответе нет содержимого.
• 400 Bad Request: Запрос содержит некорректные данные или не может быть обработан сервером.
• 401 Unauthorized: Требуется аутентификация для доступа к ресурсу.
• 403 Forbidden: У клиента нет разрешения на доступ к ресурсу.
• 404 Not Found: Запрашиваемый ресурс не найден на сервере.
• 500 Internal Server Error: Произошла внутренняя ошибка сервера при обработке запроса.

Примеры использования HTTP статусов в API:

1.) Запрос информации о пользователе:

URL: https://api.example.com/users/123Метод: GET

Ответ: Код статуса: 200 OK

2.) Создание нового пользователя:

Шаг 4 «Пример запроса (Описание API)»

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

Примеры запросов может содержать фрагменты кода, которые показывают один и тот же запрос на разных языках (помимо curl). Запросы, показанные на других языках программирования, являются необязательными (но при их наличии, пользователи приветствуют их).

Примеры запросов

Пример ниже показывает пример запроса Callfire API

Дизайн этого сайта API задуман таким образом, что примеры запросов и ответов размещаются в правом столбце страницы. Запрос отформатирован в curl, который мы рассмотрели ранее в разделе Создание curl запроса.

curl -u "username:password" -H "Content-Type:application/json" -X GET "https://api.callfire.com/v2/texts?limit=50&offset=200" 

curl — это обычный формат для отображения запросов по нескольким причинам:

• curl не зависит от языка, поэтому он не относится к какому-либо конкретному языку программирования;
• curl показывает информацию заголовка, необходимую в запросе;
• curl показывает метод, используемый в запросе.

В общем, чтобы показать пример запроса, используйте curl. Вот еще один пример запроса curl в Parse API:

Можно добавить обратную косую черту в curl, чтобы разделить каждый параметр на отдельной строке (хотя, как оговаривалось раньше, в Windows возникают проблемы с обратной косой чертой ).

Бывает и так, что сайты документации API могут использовать полный URL-адрес ресурса, например, этот простой пример из Twitter:

URL ресурса включает в себя как базовый путь, так и конечную точку. Проблема с отображением полного URL ресурса состоит в том, что он не указывает, нужно ли передавать какую-либо информацию заголовка для авторизации запроса. (Если ваш API состоит только из запросов GET и не требует авторизации, отлично, но только немногие API настроены таким образом.) Запросы curl могут легко отображать любые параметры заголовка.

Множественные примеры запросов

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

https://api.citygridmedia.com/content/places/v2/search/where 

Однако есть буквально 17 возможных параметров строки запроса, которые можно использовать с этой конечной точкой. В результате документация включает несколько примеров запросов, которые показывают различные комбинации параметров:

Добавление множественных примеров запросов имеет смысл, когда параметры обычно не используются вместе. Например, есть несколько случаев, когда можно фактически включить все 17 параметров в один и тот же запрос, поэтому любой пример будет ограничен в том, что он может показать.

В этом примере показано, как «Найти отели в Бостоне, просматривая результаты с 1 по 5 страницы в алфавитном порядке»:

https://api.citygridmedia.com/content/places/v2/search/where?what=hotels&where=boston,ma&page=1&rpp=5&sort=alpha&publisher=test&format=json 

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

Сколько разных запросов и ответов нужно показать? Вероятно, это не простой ответ, но, не более, чем несколько. Нам решать, что нужно для нашего API. Пользователи обычно вникнут в шаблон после нескольких примеров.

Запросы на разных языках

Как было сказано ранее в разделе Что такое REST API? REST API не зависит от языка. Универсальный протокол помогает облегчить широкое распространение для разных языков программирования. Разработчики могут кодировать свои приложения на любом языке, от Java до Ruby, JavaScript, Python, C #, Node JS или каком-либо еще. Пока разработчики могут отправлять HTTP-запросы на своем языке, они могут использовать API. Ответ от веб-запроса будет содержать данные в формате JSON или XML.

Поскольку невозможно знать, на каком языке будут писать конечные пользователи, попытка предоставить примеры кода на каждом языке бесполезна. Многие API просто показывают формат для отправки запросов и пример ответа, и авторы предполагают, что разработчики будут знать, как отправлять HTTP-запросы на своем конкретном языке программирования.

Однако некоторые API отображают простые запросы на разных языках. Вот пример из Twilio:

в выпадающем списке можно выбрать, какой язык использовать для примера запроса: C #, curl, Java, Node.js, PHP, Python или Ruby.

Вот еще пример API от Clearbit:

Можно увидеть запрос в Shell (curl), Ruby, Node или Python. Разработчики могут легко скопировать необходимый код в свои приложения, вместо того чтобы выяснить, как заставить запрос curl перевести на определенный язык программирования.

Предоставление различных запросов, подобных этому, часто отображаемых на вкладках, помогает упростить реализацию API. Еще лучше, если есть возможность автоматически заполнять ключи API фактическими пользовательскими ключами API на основе их авторизованного профиля.

Но нас не испугает этот шведский стол с примерами кода. Некоторые инструментальные средства API (такие как Readme.io или SwaggerHub) могут автоматически генерировать эти примеры кода, поскольку паттерны выполнения запросов REST на разных языках программирования следуют общему шаблону.

Tip: Менеджеры продуктов часто знают, на каких языках программирования целевые пользователи разрабатывают приложения. Если известен предпочитаемый язык программирования целевой аудитории, можно добавлять примеры кода только на нужном языке.

Авто генерация примеров кода

Если технический писатель не пользуется инструментом с функцией автоматической генерации примера кода, но предоставить эти фрагменты кода необходимо, то можно автоматически генерировать примеры кода из Postman и Paw.

Paw (на MacOS) позволяет экспортировать запрос практически на все мыслимые языки:

После того, как мы сконфигурировали запрос (процесс похож на Postman), можно сгенерировать фрагмент кода, выбрав Файл> Экспорт запроса.

Приложение Postman также может генерировать фрагменты кода аналогичным образом. Мы рассмотрели этот процесс раннее в разделе Изучение полезных данных JSON ответа. В Postman после конфигурации запроса, кликаем ссылку Code (которая появляется под кнопкой «Сохранить» в правом верхнем углу).

Затем выбираем нужный язык, например JavaScript> Jquery AJAX:

Note: Хотя эти генераторы кода, вероятно, полезны, они могут и не работать для нашего API. Всегда нужно просматривать примеры кода совместно с разработчиками. В большинстве случаев разработчики предоставляют примеры кода для документации, а технические писатели кратко комментируют примеры кода.

(Для практики, включающей использование сгенерированного кода jQuery из Postman, открываем разделы Изучение полезных данных JSON ответа и Доступ и вывод на страницу определенного значения JSON.)

SDK представляют инструменты для API

Часто разработчики создают SDK (комплект разработки программного обеспечения), который сопровождает REST API. SDK помогает разработчикам реализовать API с помощью специальных инструментов. API не зависят от языка, SDK зависит от языка.

Например, в одной компании был и REST API, и JavaScript SDK. Поскольку JavaScript был целевым языком, над которым работали разработчики, компания разработала SDK JavaScript, чтобы упростить работу с REST с использованием JavaScript. Стало возможным отправлять вызовы REST через JavaScript SDK, передавая ряд параметров, относящихся к веб-дизайнерам.

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

API explorer обеспечивает интерактивность с нашими собственными данными

Многие API имеют функцию API Explorer, которая позволяет пользователям делать реальные запросы непосредственно из документации. Например, вот типичная справочная страница для документов API Spotify:

API Flickr также имеют встроенный API Explorer:

Как и API New York Times:

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

Однако, если у вас нет нужных данных в вашей системе, использование собственного ключа API может не показать вам полный возможный ответ. Это работает лучше всего, когда ресурсы включают публичную информацию, а запросами являются запросы GET.

API Explorer может быть опасным в руках пользователя

Хотя интерактивность является мощным средством, API Explorer может быть опасным дополнением к вашему сайту. Что, если начинающий пользователь, который пробует метод DELETE, случайно удалит данные? Как мы позже удалим тестовые данные, добавленные методами POST или PUT?

Одно дело разрешить методы GET, но если включить другие методы, пользователи могут случайно повредить свои данные. В API Sendgrid появляется предупреждающее сообщение для пользователей перед проверкой вызовов с помощью их API Explorer:

Документация API Foursquare раньше имела встроенный API Explorer в предыдущей версии своих документов (см. Ниже), но позже его удалили. Возможно, они столкнулись с некоторыми из этих проблем.

Что касается интеграции пользовательских инструментов API Explorer, эта задача должна быть относительно простой для разработчиков. Все, что делает API Explorer, это отображает значения из поля в вызов API и возвращает ответ в тот же интерфейс. Другими словами, API-интерфейс — это все, что нужно, плюс немного понимания JavaScript и навыков фронтенда, для успешной работы.

Не обязательно создавать свои собственные инструменты. Существующие инструменты, такие как Swagger UI (который анализирует спецификацию OpenAPI) и Readme.io (который позволяет вводить детали вручную или из спецификации OpenAPI), могут интегрировать функционал API Explorer непосредственно в документацию.

Note: Пособие по созданию собственного API Explorer см. В Руководство Swagger UI.

Пример запроса для SurfReport

Вернемся к нашей конечной точке surfreport/ и создадим пример запроса для нее:

Sample Request

curl -I -X GET "https://api.openweathermap.org/data/2.5/surfreport?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial&days=2" 

Следующие шаги

Теперь, когда мы создали образец запроса, естественно, следующий шаг — включить пример ответа, который соответствует этому запросу. Также мы задокументируем модель или схему ответа. Переходим в Шаг 5: Пример и схема ответа

Варианты отправки запросов

Общаться с REST API, т.е. отправлять к нему запросы и получать ответы, можно разными способами. Собственно, этим он и удобен и для этого создан. По сути тут нет никаких ограничений: любая программа, которая умеет отправлять запросы, может управлять сайтом удаленно. Или это можно делать из самого сайта, в этом случае будут создаваться AJAX запросы к REST API. В этом разделе мы приведем несколько разных примеров кода, как можно отправлять запросы к REST API. Тут сразу нужно разделить запросы сайта к самому себе и запросы одного сайта или приложение к другому сайту. Во многом эти запросы похожи, пожалуй, самое главное отличие в них это авторизация: когда запрос отправляет самому себе, то авторизация, как правило, не нужна, а когда удаленно к сайту, то авторизацию нужно проходить отдельно, подробнее об этом читайте в разделе Аутентификация в REST API.

Оглавление:

• Как сделать внутренний запрос к REST API из плагина?
• Запрос с помощью Fetch в JavaScript
• Запрос с помощью jQuery AJAX

Как сделать внутренний запрос к REST API из плагина?

Это можно сделать с помощью функции rest_do_request(). Она создает запрос к API внутри WordPress, т.е. технически запроса не происходит:

$request = new WP_REST_Request( 'GET', '/wp/v2/posts' ); // Установим параметры запроса $request->set_param( 'per_page', 20 ); $response = rest_do_request( $request );

Запрос с помощью Fetch в JavaScript

Fetch — это веб-api, который призван заменить оригинальный метод XMLHTTPRequests для работы с AJAX и HTTP запросами. Fetch поддерживается в последних версиях современных браузеров: см. полифилл по этой ссылке, если он нужен.

var apiURL = 'http://demo.wp-api.org/wp-json'; // Получим последние записи fetch( apiURL + '/wp/v2/posts/' ) .then( response => < if ( response.status !== 200 ) < throw new Error( 'Problem! Status Code: ' + response.status ); >response.json().then( posts => < console.log( posts ); // выведем в консоль >); >) .catch(function(err) < console.log( 'Error: ', err ); >); // Получим запись с apiURL + '/wp/v2/posts/1' ) .then( response => < if ( response.status !== 200 ) < throw new Error('Problem! Status Code: ' + response.status); >response.json().then( post => < console.log( post ); >); >) .catch(function( err ) < console.error( err ); >);

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

В обоих примерах сначала выбрасываем ошибку (throw), если статус ответа не 200. Если ошибки нет, то превращаем ответ в json и обрабатываем его.

В конце ловим с помощью .catch() любые выброшенные нами ошибки.

Запрос с помощью jQuery AJAX

Пример JS кода на основе jQuery.

(function($) < var apiURL = 'http://demo.wp-api.org/wp-json'; // Получим последние записи $.ajax( < url: apiURL + '/wp/v2/posts/', success: function ( posts ) < console.log( 'Array of posts', posts ); >, error: function( err ) < console.log( 'Error: ', err ); >> ); // Получим запись с < url: apiURL + '/wp/v2/posts/1', success: function ( post ) < console.log( 'Array of posts', post ); >, error: function( err ) < console.log( 'Error: ', err ); >>); >)( jQuery );

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

$.ajax автоматически преобразует JSON ответ в массив или объект JavaScript. Поэтому тут не нужны дополнительные преобразования, можно сразу работать с ответом, как будто это объект или массив JavaScript.

Как написать удобный API — 10 рекомендаций

Я разработчик и большую часть моей карьеры я строю API различных сервисов. Рекомендации для этой статьи были собраны на основе наиболее часто встречающихся проблем при проектировании своего сервиса в команде или использовании сторонних API.

Скорее всего, вы сталкивались с провайдерами ужасного API. Работа с ними, как правило, сопряжена c повышенной эмоциональностью и недопониманием. Большую часть таких проблем можно избежать, проектируя интерфейс приложения, используя советы ниже.

1. Не используйте глаголы в URL *

* — если это одна из CRUD-операций.

За действие с ресурсом отвечают CRUD-методы запроса: POST — создать (create), GET — получить (read), PUT/PATH — обновить (update), DELETE — удалить (ну вы поняли). Плохо:

POST /users//delete - удаление пользователя POST /bookings//update - обновление бронировки

Хорошо:

DELETE /users/ PUT /bookings/

2. Используйте глаголы в URL

Плохо:

POST /users//books//create - добавить книгу пользователю

Хорошо:

POST /users//books//attach POST /users//notifications/send - отправить уведомление пользователю

3. Выделяйте новые сущности

Выше есть пример добавления книги пользователю, возможно, логика вашего приложения подразумевает список избранного, тогда роут может быть и таким:

POST /wishlist//

4. Используйте один идентификатор ресурса *

* — если ваша структура данных это позволяет.

Это значит если у вас есть записи вида один ко многим, например
бронь -> путешественники (booking->travellers), вам будет достаточно передавать в запросе идентификатор путешественника.

Плохо:

# получение данных путешественника GET /bookings//travellers/

Хорошо:

GET /bookings/travellers/

Также замечу, что /bookings/travellers/ лучше, чем просто /travellers . Хорошо придерживаться иерархии данных в своем API.

5. Все ресурсы во множественном числе

Плохо:

GET /user/ - получение данных пользователя POST /ticket//book - бронирование билета

Хорошо:

GET /users/ POST /tickets//book

6. Используйте HTTP-статусы по максимуму

Самый простой способ обработки ошибок — это ответить соответствующим кодом состояния. В большинстве случает один этот статус может дать исчерпывающую информацию о результате обработки запроса. Одни из самых распространенных кодов ответов:

• 400 Bad Request — клиент отправил неверный запрос, например, отсутствует обязательный параметр запроса.
• 401 Unauthorized — клиенту не удалось пройти обязательную аутентификацию на сервере для обработки запроса.
• 403 Forbidden — клиент аутентифицирован, но не имеет разрешения на доступ к запрошенному ресурсу.
• 404 Not Found — запрошенный ресурс не существует.
• 409 Conflict — этот ответ отправляется, когда запрос конфликтует с текущим состоянием сервера.
• 500 Internal Server Error — на сервере произошла общая ошибка.
• 503 Service Unavailable — запрошенная услуга недоступна.

7. Модификаторы получения ресурса

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

Пример: /quizzes и /quizzes/passed . Здесь quizzes — ресурс (викторины), passed — модификатор (пройденные).

Плохо:

GET /passed-quizzes - получение пройденных викторин GET /booked-tickets - получение забронированных билетов POST /gold-users - создание премиум пользователя

Хорошо:

GET /tickets/booked POST /users/gold

8. Выберите одну структуру ответов

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

Плохо:

GET /book/

Хорошо:

GET /book/  < "status": 0, "message": "ok", "data": >

В этом примере 3 поля универсальны и могут использоваться для любого ответа от апи. status , message — собственный статус и сообщение приложения по которому клиент сможет ориентироваться, эти поля сообщат ему дополнительную информацию о процессе обработки запроса, но не данные ресурса. Например, в нашем приложении в один момент времени, пользователь может проходить только одну викторину. Тогда запрос на начало новой может выдать 409-й статус, а в полях status и message — дополнительную информацию, почему была получена ошибка.

9. Все параметры и json в camelCase

9.1 В параметрах запросов
Плохо:

GET /users/ GET /users/ GET /users/

Хорошо:

GET /users/ POST /ticket//gold

9.2 В теле ответа или принимаемого запроса
Плохо:

Хорошо:

10. Пользуйтесь Content-Type

Плохо:

GET /tickets.json GET /tickets.xml

Хорошо:

GET /tickets // и в хедере Сontent-Type: application/json // или Сontent-Type: application/xml

Заключение

Перечисленные выше рекомендации это далеко не весь список способов сделать API лучше. Для дальнейшего изучения рекомендую разобрать спецификации REST API и список кодов http-статусов (вы удивитесь, насколько их много и какие ситуации они охватывают).

А в комментариях предлагаю написать свою рекомендацию по построению REST API, которую вы считаете важной.