До этого момента мы выступали в роли разработчика с задачей интеграции данных о погоде на свой сайт. Цель состояла в том, чтобы понять, какая информация нужна разработчикам и как они используют API.
Теперь сменим роль. Теперь у нас роль технического писателя, работающего в команде OpenWeatherMap. Команда просит задокументировать новую конечную точку. Что будем писать, какой поход применим?
Нужно документировать новую конечную точку
Менеджер проекта вызывает и говорит, что у команды есть новая конечная точка, которую нужно документировать к следующему релизу. (Иногда команды называют каждую конечную точку «API».)
«Вот вики-страница, которая содержит информацию о новом API», - говорит менеджер. вся информация разбросана в случайном порядке.
Большинство технических писателей не начинают с нуля документацию проекта. Инженеры обычно помещают важную информацию на внутреннюю вики (или передают информацию во время встреч). Однако информация на вики-странице, скорее всего, будет неполной и излишне технической в некоторых местах (например, описание схемы базы данных или высокоуровневых архитектурных рабочих процессов). Информация может также включать в себя только внутреннюю информацию (например, тестовые логины, протоколы доступа или кодовые имена) или содержать давно устаревшие разделы.
В конечном счете, информация будет ориентирована на других инженеров того же уровня знаний, что и инженеры команды. Работа технического писателя заключается в том, чтобы взять эту информацию и превратить ее в полную, точную, полезную информацию, которая сообщается аудитории.
wiki-страница с информацией о новой конечной точке
Теперь наша задача отсортировать информацию на той фиктивной вики-странице и создать из нее документацию. Можно прочитать макет вики-страницы ниже, чтобы получить представление об информации. В следующих разделах мы будем знакомиться с каждой секцией API.
Вот мок внутренней вики-страницы:
Wiki страница: “Surf Report API”
Конечной точкой является /surfreport/{beachId}. Эта конечная точка предназначена для сёрферов, которые хотят проверить такие вещи, как прилив и волны, чтобы определить, следует ли им отправиться на пляж для серфинга. {beachId}
взято из списка пляжей на нашем сайте.
Необязательные параметры:
- Количество дней: Максимально = 7. По умолчанию стоит 3. Не обязательно.
- Единицы измерения: Метрические или имперские. Имперские единицы: футы и узлы. Метрические единицы: сантиметры и километры в час. Не обязательно.
- Время: время дня, соответствующее часовому поясу пляжа, о котором пришел запрос. Формат unix time, он же эпоха. Время Unix - это миллисекунды с 1970 года. Часовой пояс - GMT или UTC.
Если добавить час, то в ответе будет состояние прогноза только за указанный час. В противном случае будет прогноз за 3 дня с условиями, перечисленными по часам для каждого дня.
Ответ будет включать в себя высоту прибоя, ветер, температуру, прилив и общую рекомендацию.
Пример конечной точки с параметрами:
https://api.openweathermap.org/com/surfreport/123?&days=2&units=metrics&hour=1400
Ответ содержит три элемента:
Отчет:
- высота прибоя (единица измерения: футы)
- ветер (единица измерения: узел)
- волна (единица измерения: футы)
- температура воды (единицы измерения: градусы по Фаренгейту)
- рекомендации - строка (“Go surfing!”, “Surfing conditions okay, not great”, “Not today – try some other activity.”)
Рекомендация основана на алгоритме, который выбирает оптимальные условия серфинга, оценивает их по рубрике и включает один из трех ответов.
Образец формата:
{
"surfreport": [
{
"beach": "Santa Cruz",
"monday": {
"1pm": {
"tide": 5,
"wind": 15,
"watertemp": 60,
"surfheight": 5,
"recommendation": "Go surfing!"
},
"2pm": {
"tide": -1,
"wind": 1,
"watertemp": 50,
"surfheight": 3,
"recommendation": "Surfing conditions are okay, not great"
}
...
}
}
]
}
Отрицательные значения прилива означают поступающий прилив.
Отчет не будет содержать параметров разрывных течений.
Хотя пользователи могут вводить названия пляжей, в отчет включены только определенные пляжи. Пользователи могут посмотреть, какие пляжи доступны на нашем сайте по адресу http://example.com/surfreport/beaches_available. При передаче в конечной точке имена пляжей должны быть закодированы в виде строк запроса.
Для переключения единиц измерения в строке меняется параметр &units=metrics. По умолчанию стоит &units=imperial.
Вот пример того, как разработчики могут интегрировать информацию
Если запрос искажен, вы получите код ошибки 400 и указание на ошибку.
Как видно, информация в примере wiki-страницы не структурирована и ее трудно читать. Путем разделения информации API на пять стандартных разделов информация приобретет лучшую форму и станет более читабельной.
Следующие шаги
Давайте перейдем к Обзору пошагового описания API для изучения пяти шагов, которые мы рассмотрим при создании раздела адресного API для этой новой конечной точки.