Lesson 2

Lesson 2

Volume 2

Lesson 2

Что такое спецификация?
API-документация или же спецификация - это техническая документация, в которой фиксируются инструкции о том, как использовать и как должнен работать API. Или же если сказать проще, спецификация - это документ, с помощью которого, один разработчик понимает другого разработчика.

Что должно быть указано в спецификации:

  • Какие методы можно использовать, посылая запросы на каждый URI - на какой URL ;

  • Какие будут передаваться данные - описание всех параметров, которые будут передаваться на сервер или могут прийти от сервера;

  • Если нужно передавать данные в теле запроса, то какие это данные;

  • Какие ответы мы ожидаем в случае успешного запроса;

  • Какие ответы мы ожидаем когда с запросом или его обработкой на сервере что-то не так;

  • Описание всех типов данных, которые мы передаем на сервер - для каждого параметра, помимо описания, должно быть указаны и типы данных.

Сервисы для написания спецификации
Сервисов для написания спецификации существует множество, но мы рассмотрим самые популярные из них:


Примеры спецификаций:



Тестирование спецификации
Что тестируется в спецификации:

  • наличие описания параметров;
  • описание типов данных для передаваемых параметров;
  • является ли передаваемый параметр обязательным или нет
  • соответствие метода, и передаваемых данных;
  • коды ошибок, которые будут использоваться в response;
  • тексты ошибок, которые будут использоваться;
  • примеры всей модели запроса: пример запроса и пример ответа
Типы данных
Мы упоминаем разные типы данных, ниже приведен список основных для понимания контекста.

Логические, или булевы значения, могут иметь лишь одно из двух состояний — «истина» или «ложь» (true or false) . В разных языках обозначаются bool, BOOL, или boolean. «Истина» может обозначаться как true, TRUE или #T. «Ложь», соответственно, false, FALSE или #F

Регулярный тип, или массив, есть упорядоченный набор данных одинакового типа.
Элементами массива могут быть данные любого типа.

INTEGER (целый). Этот тип представляет множество целых чисел диапазона от -32768 до 32767. Исключительно целые числа.

String (строковый тип) — тип данных, значениями которого является произвольная последовательность (цепочка) символов, передаётся в кавычках.

Практическое задание

Протестировать спецификацию https://trelloforsecoundlesson.docs.apiary.io , а именно запросы с методами GET, PUT, DELETE.

Оформить ошибки как показано в уроке. Пример документа можно скачать по ссылке Download.

Найденные ошибки оформить в exсel файл. Подгрузить файл можно нажав на кнопку Upload file и выбрав папку со своим именем.