#2 Читаем Swagger ~ 10 мин

  1. Заходим на API Portal – REST Bootcamp (поиском в каталоге API до спецификации или просто, нажав на ссылку)
  2. Перед вами удобное для чтения представление спецификации в формате Swagger/OpenAPI. Исходный файл имеет формат JSON или YAML.
  3. Выделенные цветом участки спецификации (разожмём блок Customer, нажав на него левой кнопкой мыши) будем называть endpoint или ресурсом
  4. Просмотрите отдельные endpoints — обратите внимание, что есть GET, POST, PUT и DELETE. GET позволяет запрашивать клиентов, POST — создавать новых, PUT — обновлять существующего, а DELETE — удалять клиента.
  5. Каждый эндпоинт сопровождается кратким текстом описания. Он дает вам подсказки, чего вы можете достичь, вызвав API, например:
    GET /customers Список всех клиентов.
  6. Обратите внимание, что для некоторых эндпоинтов требуется path-parameter (параметр пути) (например, GET /customers/{id}). Параметры пути обычно используются для идентификации объекта, который должен быть вызван.
  7. Если вы нажмете на поле, например. POST /customers — открывается подробная информация об этой конечной точке.
  8. Детали разделены на несколько разделов. Параметры и тело запроса описывают, какие входные данные требуются REST API, а ответ описывает, какие будут выходные данные после вызова.
  9. Обратите внимание на область «Тело запроса» внутри параметров. Когда мы смотрим на конечную точку POST (создание клиента), нам нужно иметь возможность передавать данные клиента в API. Структура этих данных описана в разделе «Тело запроса». Вы можете видеть, что тело запроса является обязательным параметром в этой конечной точке, поэтому вы ДОЛЖНЫ указывать его при каждом вызове. Пропуск Body вызовет ошибку.
  10. Прокрутите вниз, пока не дойдете до ответов. Этот раздел содержит коды состояния HTTP, которые могут быть возвращены этим интерфейсом. HTTP 201 указывает на статус успешного вызова, а все остальные ответы считаются ошибками. Вы также можете найти примеры значений в поле «Example Value» и схему «Schema», которые определяют тело ответа.
  11. Снова прокрутите вверх до раздела «Request Body» (Тело запроса). Нажмите на ссылку «Schema» (рядом с Example Value).
  12. Схема дает вам гораздо больше деталей о спецификации API. Она содержит описания полей, дает вам ожидаемые форматы (строка, число) и часто содержит примеры, которые можно заполнить в таком поле.
  13. Закройте POST /customers и откройте описание для GET /customers/{id}.
  14. {id} указывает, что конечной точке требуется параметр «id». В разделе «Параметры» вы можете найти дополнительную информацию. Вы видите, что требуется «id», это параметр пути, и в описании сказано, что он представляет собой идентификатор клиента. В текстовом поле ниже вы найдете образец идентификатора (3790dcbe-ff08-4f7a-82f6-fd963d032095). Информация в примерах необязательно доступна в интерфейсе, но если она есть, то дает полное представление о том, какие данные необходимо передать.
  • Успешные коды состояния HTTP всегда начинаются с HTTP 2xx.
  • Вы заметите, что некоторые вызовы дают HTTP 200, некоторые HTTP 201 и некоторые HTTP 204. Как мы узнали на теоретических занятиях, все коды состояния 2xx указывают на успешный результат.
  • HTTP 200 (Успех) указывает, что конечная точка вернет содержимое в теле ответа. HTTP 204 (без содержимого), что тело ответа пусто. HTTP 201 (Created) указывает, что ресурс был создан.
  • HTTP 200 часто используется в вызовах GET (которые подразумевают, что вы получаете данные обратно).
  • HTTP 201 часто используется с операторами POST — часто ответ содержит только очень короткое тело, например, идентификатор нового объекта.
  • HTTP 204 часто используется в операторах DELETE, когда тело не должно возвращаться.
  • Подробнее о кодах состояния HTTP можно почитать в Википедии