answeres-whats-wrong.md

Описание ошибок

Здесь разберем ошибки в описании конечной точки Surfreport из практического занятия: Что не так с разделом API?

Описание ресурса

• много слов, описание должно быть более кратким и ориентированным на действия;
• "Surfreport", в названии не следует использовать заглавные буквы.

Конечные точки

• GET/POST: должен быть только один метод, в этом случае GET;
• лишнее двоеточие {:beachId};
• можно выделить цветом {beachId}

Параметры

• параметры строки запроса перемешаны в одной и той же таблице, что и параметры Path. Лучше разделить на разные таблицы;
• не понятно, где брать ID пляжа;
• Number и Integer потенциально противоречивы. Технически Number относится к числу с плавающей запятой (float) или к (double) (что допускает десятичные дроби), а Integer - это целое число. В данном случае вряд ли идентификаторы пляжа имеют десятичные дроби;
• отсутствует значение параметра time по умолчанию;
• что касается типов данных time: почему некоторые типы данных имеют примеры, но не все?

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

• пример запроса не в формате curl;
• показан только один параметр строки запроса, time тоже должно быть;
• включен параметр zip, но нигде не определен;
• appID включает длинный ключ API, который, должен быть сокращен до такой переменной, как APIKEY.

Пример ответа

• включен riptide, но отсутствует его определение в определениях ответа;
• у riptide отсутствует запятая во втором экземпляре;
• riptide не указан в третьем экземпляре;
• неверное форматирование отступа для riptide.

Определения ответа

• для параметра wind не указаны единицы измерения;
• для параметра wind "int" следует указывать как "integer";
• для параметра watertemp не указаны единицы измерения;
• тип данных для surfheight указан как "Map", а должен быть "integer";
• recommendation не включает в себя более подробную информацию, например, сколько возможных строк с рекомендациями и что они вообще значат;
• surfheight должен быть одинаковым: или surf_height или surfheight и в примере ответа и в таблице определений ответа;
• отсутствует иерархия для дочерних элементов (пример: tide, wind, watertemp)