Edit me

Давайте соберем различные части вместе, чтобы продемонстрировать полный пример конечной точки:

Surfreport

Содержит информацию об условиях серфинга, включая высоту прибоя, температуру воды, ветер и прилив. Также предоставляет общую рекомендацию о том, стоит ли заниматься серфингом.

Endpoints

GET surfreport/{beachId}

Получает условия серфинга для определенного идентификатора пляжа.

Параметры

Параметры path

Параметр path Описание
{beachId} Относится к идентификатору пляжа, который вы хотите посмотреть. Все коды beachId доступны на нашем сайте sampleurl.com.

Параметры строки запроса

Параметр строки запроса Обязательно/ необязательно Описание Тип данных
days Optional Количество дней, включаемых в ответ. По умолчанию = 3 Integer
time Optional При указании времени в ответе будет выводиться только указанный час Integer. Unix format (ms since 1970) UTC

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

curl -I -X GET "https://api.openweathermap.org/data/2.5/surfreport?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial&days=2"

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

Ниже пример ответа конечной точки surfreport/{beachId}

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 80,
                    "surfheight": 5,
                    "recommendation": "Go surfing!"
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surfheight": 3,
                    "recommendation": "Surfing conditions are okay, not great."
                },
                "3pm": {
                    "tide": -1,
                    "wind": 10,
                    "watertemp": 65,
                    "surfheight": 1,
                    "recommendation": "Not a good day for surfing."
                }
                ...
            }
        }
    ]
}

В таблице ниже описание для каждого пункта

Пункт ответа Описание Тип данных
beach Пляж, выбранный на основе идентификатора пляжа в запросе. Название пляжа - это официальное название, описанное в базе геоданных Службы национальных парков. string
{day} Выбранный день недели. В ответ возвращается максимум 3 дня. Object
{time} Выбранное время для погодный условий. Этот элемент включается только в том случае, если в запрос включен параметр времени. string
{day}/{time}/tide Уровень прилива на пляже в определенный день и время. Прилив - это расстояние внутри страны, до которого поднимается вода, и может быть положительным или отрицательным числом. При отливе, число отрицательное. При приливе, число положительное. Точка 0 отражает линию, при отсутствии прилива/отлива, и находится в переходе между двумя состояниями. Integer
{day}/{time}/wind Скорость ветра на пляже измеряется в узлах (морских миль в час). Ветер влияет на высоту прибоя и общие условия волнения. Скорость ветра более 15 узлов делает условия серфинга нежелательными, потому что ветер создает белые шапки и неспокойную воду. Integer
{day}/{time}/watertemp Температура воды, возвращаемая в градусах Фаренгейта или Цельсия, в зависимости от указанных единиц измерения. Для температуры воды ниже 70 F может потребоваться гидрокостюм. При температуре ниже 60, вам понадобится как минимум 3-миллиметровый гидрокостюм и желательно пинетки, чтобы согреться. Integer
{day}/{time}/surfheight Высота волн возвращается в футах или сантиметрах в, зависимости от указанных единиц измерения. Высота прибоя 3 фута - минимальный размер, необходимый для серфинга. Если высота прибоя превышает 10 футов, заниматься серфингом небезопасно. Integer
{day}/{time}/recommendation Общая рекомендация, основанная на сочетании различных факторов (ветер, температура воды, высота полета). Возможны три варианта ответа: (1) «Займитесь серфингом!», (2) «Условия серфинга в порядке, но не круто», и (3) «Не очень хороший день для серфинга». Каждый из трех факторов оценивается максимум в 33,33 балла, в зависимости от идеала для каждого элемента. Три элемента объединены, чтобы сформировать процент. От 0% до 59% дает ответ 3, от 60% до 80% дает ответ 2, а от 81% до 100% дает ответ 3. String

Вот и все. При наличии множества конечных точек для документирования, вероятно, проще создать шаблоны, которые следуют общей структуре. Более того, использование спецификации OpenAPI при документировании делает публикацию контента еще проще. Подробнее мы рассмотрим спецификацию OpenAPI в модуле Спецификация OpenAPI и Swagger

Следующие шаги

Мы закончили Обзор пошагового описания API и теперь готовы к практике:

но сначала попробуем поискать ошибки в документации

🔙

Go next ➡