· обновлено
Вопросы про API, которые неловко задать вслух
На третьей неделе работы некоторые вопросы задавать уже неловко. Вокруг говорят «дёрни ручку», «там 403, выдай права», «глянь в заголовках», а вы киваете и потом тихо гуглите.
Мы собрали семь таких вопросов и ответили на них без единой строчки кода, на конвертах и пропусках.
1. Что такое запрос, если по-человечески?#
Письмо. Самое обычное, в конверте.
На конверте написано, куда его доставить и что с ним сделать: «покажите заказ 42» или «добавьте к заказу 42 комментарий». Это адрес и метод. Ещё на конверте наклеены марки: кто отправитель, на каком языке ответить, что лежит внутри. Это заголовки. А внутри лежит само письмо, то есть тело запроса. Бывает, что конверт пустой: чтобы попросить показать заказ, писать ничего не нужно.
Сервер вскрывает письмо и присылает ответ, тоже в конверте. Главное на ответном конверте стоит сверху: трёхзначный номер, код ответа. По нему сразу видно, чем всё закончилось, ещё до того как вы прочитали содержимое.
2. Что значит «дёрнуть ручку»?#
На жаргоне «ручкой» называют конкретный адрес вместе с методом. Например, GET /orders/42 показывает заказ, а POST /orders создаёт новый. Чем больше ручек у сервиса, тем больше он умеет.
«Дёрнуть» значит отправить запрос один раз и посмотреть, что вернётся. Так просто короче, чем «отправь, пожалуйста, GET-запрос на адрес такой-то».
3. Чем 401 отличается от 403? И при чём тут 404?#
Коротко: 401 значит, что сервер не понял, кто вы: токена нет, он просрочен или чужой. Это ошибка аутентификации. 403 значит, что сервер вас узнал, но прав на это действие у вас нет. Это ошибка авторизации. 404 значит, что по адресу ничего нет.
Проще всего объяснить это на пропуске в офис.
401. Пропуск не сработал: его нет, он просрочен или чужой. Нужно войти заново или обновить токен.
403. Пропуск рабочий, но эту дверь не открывает. Прикладывать его снова бесполезно, нужны права. Пишите тому, кто их раздаёт.
404. Такой комнаты в здании нет. Опечатка в адресе, не тот сервер или заказ 42 давно удалили.
Остальные коды тоже легко запомнить по первой цифре:
| Код | Что случилось | Что делать |
|---|---|---|
| 200 | Всё хорошо, вот ответ | радоваться, но заглянуть в ответ: там может быть не то, что вы ждали |
| 201 | Создано | новый заказ или пользователь уже на сервере |
| 204 | Готово, но в ответе пусто | так часто отвечают на удаление |
| 301 | Переехало по другому адресу | клиент обычно сам переходит по новому адресу |
| 400 | Сервер не понял, что вы написали | проверить тело и параметры: опечатка, пропущенное поле |
| 429 | Слишком много запросов | подождать и сбавить темп |
| 500 | На сервере что-то сломалось | вы, скорее всего, ни при чём; отправить разработчикам время и запрос |
| 502 | Посредник не достучался до сервера | чаще всего проблема на стороне сервера, попробовать позже |
| 503 | Закрыто на обед | сервер перегружен или обновляется, попробовать позже |
Если код начинается с 2, всё прошло. С 3, вас перенаправили. С 4, что-то не так с запросом. С 5, что-то не так с сервером. Это грубое правило, но в девяти случаях из десяти оно подсказывает, кому писать.
4. Зачем заголовки, если есть тело?#
Сервер читает конверт раньше, чем вскрывает письмо. Из заголовков он узнаёт, кто пишет (Authorization), что лежит внутри (Content-Type: application/json) и на каком языке хочется ответ (Accept-Language).
Если заголовка не хватает, до тела дело может не дойти. Забудете Authorization, и получите 401, даже если письмо написано идеально.
5. Почему в браузере работает, а в Postman 401?#
Браузер носит пропуск за вас. Когда вы вошли на сайт, он сохранил пропуск, чаще всего cookie, и с тех пор сам прикладывает его к каждому запросу. Вы этого не видите, поэтому кажется, что запрос «просто работает».
Postman, Tetiva или другой API-клиент про ваш вход в браузере ничего не знает, поэтому запрос без cookie или токена получает 401. Пропуск нужно получить заново: отправить запрос на вход прямо из клиента или взять токен у коллег так, как у вас в команде принято. Tetiva, например, запоминает cookie после запроса на вход и дальше прикладывает их сама, как браузер.
6. Можно ли что-то сломать, нажав Send?#
Можно. Поэтому полезно смотреть на метод. GET по правилам только читает, а POST, PUT, PATCH и DELETE меняют данные на сервере. Ещё они по-разному переживают повторное нажатие:
Две оговорки. Правила иногда нарушают, и где-то GET тоже умеет что-то менять, поэтому на проде осторожнее со всем подряд. И второе: важно не только что вы отправляете, но и куда. Как запрос улетает не в то окружение, мы рассказали в истории про пятницу, 18:40.
7. Чем коллекция отличается от истории?#
История похожа на журнал звонков. Туда само собой попадает всё, что вы отправляли, включая неудачные попытки и опечатки. Удобно, чтобы найти вчерашний запрос или точное время, когда что-то пошло не так.
А коллекция похожа на записную книжку. В неё вы сами кладёте запросы, которые хотите сохранить, и даёте им понятные имена. Коллекцию отдают коллегам, история обычно остаётся у вас. Если записная книжка у вас в команде превратилась в пять файлов с именами final_v2, вот что с этим делать.
Где потренироваться#
Ответы 401, 403 и 404 можно увидеть своими глазами. Для этого есть учебные сервисы, например наш бесплатный тестовый API на playground.tetiva.app: он отвечает тем кодом, который вы попросили.
- Откройте любой API-клиент. Tetiva подойдёт, она бесплатная и запускается без регистрации.
- Отправьте
GET https://playground.tetiva.app/status/401, потом то же с403и404. Меняется только код, короткое JSON-тело его просто повторяет. А у 401 в заголовках найдётсяWWW-Authenticate: так сервер подсказывает, какой пропуск он ждёт. - Отправьте
GET https://playground.tetiva.app/headers. Сервер вернёт заголовки, которые получил от вас. Добавьте свой заголовок и отправьте ещё раз.
Пять минут, и следующее «там 403» уже не придётся тихо гуглить.