Edit me

Здесь разберем ошибки в описании конечной точки 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)

🔙

Go next ➡