Представьте, что вы командуете роботом-курьером. Если сказать ему «Доставь что-нибудь вкусненькое», он сломается. Нужна четкая инструкция: «Привези пиццу «Маргарита» из кафе на Ленина, 10, квартира 44». API-спецификация - это и есть такие инструкции для одной программы, которая объясняет другой, как правильно просить данные или совершать действия.

Вот 7 простых правил, как писать эти инструкции, чтобы их понял даже новичок.

Правило 1. Говори на понятном языке

В мире API есть всего несколько базовых «команд» (глаголов). Их нельзя путать.

· GET (получить) - попросить информацию. Как спросить «который час?» без внесения изменений. · POST (отправить/создать) - отправить новые данные, чтобы что-то создать. Как, например, отправить заявку на покупку. · PUT (положить/заменить) - полностью заменить старые данные новыми. Как переписать всю страницу в тетради. · DELETE (удалить) - удалить что-либо.

Пример: Неправильно (робот запутается): Сделай POST-запрос на /getUser - тут смешаны понятия «отправить» и «получить». Правильно: Сделай GET-запрос на /users/44. Читается как: «Получи (GET) информацию о пользователе (users) с номером 44».

Правило 2. Ты всегда должен отвечать

После каждой команды робот должен дать понятный ответ, а не просто «ок».

· 200 OK - все получилось, держи, что просил. · 201 Created - «Я только что создал по твоей просьбе новую вещь!» (после POST-запроса). · 400 Bad Request - «Ты прислал мне какую-то хрень, я тебя не понял». · 404 Not Found - «То, что ты просишь, я не нашел. Возможно, ты ошибся номером». · 500 Internal Server Error - «У меня на стороне что-то сломалось, уже чиним».

Важно: Если произошла ошибка (4xx или 5xx), в ответе нужно объяснить ее человеческим языком: {“error”: “Неверный email: такой уже существует”}.

Правило 3. Учитывай будущее спецификации, а именно ее версионность.

Представьте, что вы обновили рецепт пиццы для робота. Старый робот со старым рецептом должен продолжать работать. Для этого указывают версию инструкций прямо в адресе:

· https://api.bakery.com/**v1**/pizza - старая, проверенная версия. · https://api.bakery.com/**v2**/pizza - новая, с новыми полями.

Так старые клиенты не сломаются.

Правило 4. Дели информацию на страницы

Если попросить робота: «Привези все заказы за 5 лет», он привезет гору бумаг и увязнет. Лучше просить по частям:

· «Привези первые 50 заказов» /: GET /orders?limit=50 · «А теперь следующие 50»: GET /orders?limit=50&offset=50 Это называется пагинация.

Правило 5. Справочник должен быть один

Нельзя, чтобы рецепт пиццы был в одном документе Word, а дополнения к нему - в почте, заметках или на стикере. Все инструкции должны быть в одном месте - в специальном документе (чаще всего в формате OpenAPI). Из этого одного документа можно:

· Автоматически создать красивую страницу-справочник. · Сгенерировать тестового робота для проверки. · Не дать разработчикам запутаться в разных версиях.

Правило 6. Ключ от двери и лимиты (Безопасность)

Не каждый может командовать роботом.

1. Ключ (Токен): чтобы отдать команду, нужно предъявить специальный ключ-пароль (в заголовке Authorization: Bearer …). 2. Лимит запросов: чтобы никто не мог заспамить робота тысячами запросов в секунду, вводят лимит. Робот отвечает: «Ты сделал уже 100 запросов сегодня, приходи завтра» (статус 429 Too Many Requests).

Правило 7. Защита от случайных повторов

Интернет может «глюкнуть». Вы отправили POST-запрос на создание заказа, не получили ответ и нажали «Отправить» еще раз. Чтобы не создались два одинаковых заказа, используют Idempotency-Key. Это уникальный «номер попытки». Если вы отправите второй запрос с тем же номером, робот поймет, что это повтор, и просто вернет результат первого, не создавая дубликата.

Главный итог. Хорошая API-спецификация - это забота о том, кто будет ей пользоваться. Ваша цель, чтобы другой разработчик (или вы сами через полгода), открыв документ, за 15 минут понял, как все работает, и не тратил часы на угадывание и переписку.

А по вашему опыту, что чаще всего забывают указать в API-спеках? Или, наоборот, что является самым спорным моментом?