REST API для начинающих: ресурсы, методы, коды состояния и отсутствие состояния

«Изучите REST API» — это совет, который слышит каждый новичок-разработчик, однако редко приводится чёткое объяснение того, что означает эта фраза. Большинство объяснений либо затопляют читателя специальной терминологией (глаголы, точки входа, отсутствие состояния), либо сводят их к формулировке «то, что соединяет фронтенд и бэкенд», что действительно верно, но не даёт никакой полезной информации.

В этом руководстве выбран средний путь. Вы узнаете о пяти основных принципах, из которых состоит практически любой REST API, о методе мышления, помогающем лучше их запомнить, о том, где применяется REST в повседневной инженерной работе, а также о практической последовательности создания и тестирования вашего первого API с использованием Node.js и Express, включая ошибки, которые чаще всего замедляют продвижение начинающих.

Kраткое определение

REST API — это набор конвенций, позволяющих двум программам взаимодействовать через Интернет. Чаще всего это фронтенд, запрашивающий у бэкенда данные или просящий его что-то сохранить. Идея кажется абстрактной, пока вы её не реализуете, после чего она быстро становится понятной. Именно поэтому REST обычно является одним из первых настоящих концептов бэкенда, которые изучают люди, независимо от того, будут ли они специализироваться на работе с серверной частью или станут полноценными разработчиками full stack, занимающимися обеими сторонами приложения.

REST — это аббревиатура от Representational State Transfer, архитектурный стиль, сформализованный для описания того, как должна работать сама веб-среда. Чтобы эффективно им пользоваться, не нужна формальная теория; на практике REST API опираются на приведённые ниже стандартные конвенции.

Почему REST так сбивает с толку многих начинающих

Два фактора делают эту тему сложнее, чем она должна быть.

Первая проблема — это изменение словарного запаса. В интернете термин «API» используется практически для любого интерфейса, который одно программное обеспечение предоставляет другому: API браузера, функции библиотеки, облачный сервис. REST — это один из конкретных и очень популярных способов разработки веб-API. Благодаря его широкому распространению люди часто говорят «API», имея в виду «REST API», и учащиеся остаются в недоумении относительно того, где заканчивается одна концепция и начинается другая.

Вторая проблема заключается в том, что у API нет визуального интерфейса. Кнопка или макет — это то, что можно увидеть; REST API же им не обладает. Вполне возможно месяцами работать над фронтенд-проектами, рассматривая «запрос к API» как чёрный ящик. Путаница обычно возникает тогда, когда необходимо создать собственный API, и концепция должна стать немедленно конкретной.

Пять основных принципов любого REST API

Если отбросить аббревиатуры, REST API — это утверждённый способ запроса и отправки данных по HTTP с использованием URL и небольшого набора стандартных действий. Пять основных принципов охватывают практически всё, что связано с ним.

Ресурсы и их URL

Ресурс — это объект, которым управляет API: пользователи, публикации, заказы, задачи. Каждый ресурс или группа ресурсов имеет свой собственный адрес. /users обычно относится к группе пользователей, в то время как /orders/42 — к конкретному заказу. Хорошее проектирование REST использует существительные для названия ресурсов, позволяя методам HTTP описывать действия; поэтому используется /orders/42, а не /getOrder?id=42.

Методы HTTP

Метод указывает серверу, что вы хотите сделать с ресурсом:

• GET — считывает данные без их изменения.

POST создает что-то новое, обычно внутри коллекции, такой как /tasks.

PUT заменяет существующий ресурс, в то время как PATCH обновляет его часть.

DELETE удаляет его.

Одной из характеристик, которую стоит изучить сразу, является идемпотентность. От методов GET, PUT и DELETE ожидается, что они будут идемпотентными: отправка одинакового запроса дважды оставляет сервер в том же состоянии, что и при его отправке один раз. Метод POST обычно не является идемпотентным, поскольку два одинаковых запроса могут создать две записи. Это различие объясняет многие решения при проектировании API, например, почему повторные попытки безопасны для некоторых вызовов, а опасны для других.

Запросы и ответы

Клиент отправляет запрос на один из этих URL. В запросе указываются метод, URL, заголовки (метаданные, такие как тип содержимого или токен авторизации), а для методов вроде POST или PATCH — тело запроса. Сервер отвечает ответом, содержащим код состояния, заголовки и обычно тело ответа. В современных API это тело почти всегда представляет собой JSON.

Коды состояния

Каждый ответ сопровождается трёхзначным числом, которое отражает результат. Для успешного выполнения будет показано 200, если ресурс отсутствует — 404, а при сбое на сервере — 500. Первая цифра указывает на категорию ответа: 2xx означает успех, 4xx — что клиент отправил информацию, которую сервер не может принять (неверный запрос, отсутствие аутентификации, неизвестный ресурс), а 5xx — что у самого сервера возникла проблема. Сначала определив категорию, вы быстро поймёте, в какой части системы следует искать причину.

Безсостоянийность

Каждый запрос должен содержать всё необходимое для обработки сервером. Сервер не полагается на запоминание того, о чём вы просили мгновение назад. Если, например, конечная точка требует аутентификации пользователя, каждый запрос включает учетные данные, часто токен в заголовке. Безсостоянийность делает REST-API легкими для масштабирования: любая инстанция сервера может обрабатывать любой запрос, поскольку ни одна из них не зависит от приватной памяти разговора.

Как только эти пять принципов станут понятны, документация к REST-API перестанет казаться иностранным языком. Почти каждая страница с ссылками — это просто список ресурсов, методов, которые они поддерживают, формата тел запроса и ответа, а также кодов состояния, которые могут быть получены.

Ментальная модель: заказ в ресторане

Ресторан — это удобная аналогия. Клиенты не заходят на кухню и сами готовят еду. Они читают меню, сообщают официанту, что хотят заказать, а кухня готовит блюдо и подаёт его.

• Меню — это документация API: в нём перечислено, что можно заказать.
• Официант — это цикл запроса и ответа, который передаёт ваш заказ на кухню и возвращает результат.
• Кухня — это сервер, выполняющий работу, которую вы не видите напрямую.

Если говорить с точки зрения методов, GET используется для получения информации о том, что есть в меню, или для проверки содержимого вашего столика. POST предназначен для оформления нового заказа. DELETE — для возврата блюда обратно. Вам не нужно знать, как именно организована кухня внутри; достаточно правильно оформить заказ, и вы всегда получите предсказуемый и одинаковый результат. Эта аналогия имеет свои ограничения (рестораны запоминают ваш столик, в то время как безсостоянийский API этого не делает), но хорошо отражает разделение обязанностей.

Где применяется REST в реальной инженерной практике

REST — это не просто теоретический интерес из учебников. Он является частью повседневной работы практически в каждой команде по разработке продуктов:

• Разработчик фронтенда обращается к REST-эндпоинтам для загрузки профиля, отправки формы или обновления панели управления.

Разработчик бэкенда проектирует и обслуживает эти конечные точки, определяя, какие данные возвращаются и в каком формате.

Разработчик полного стека выполняет обе задачи: иногда проектируя конечную точку, а иногда используя её в интерфейсе пользователя в тот же час.

Мобильные приложения, интеграции с сторонними сервисами и партнерские компании часто взаимодействуют с продуктом исключительно через его REST API, без какого-либо участия пользовательского интерфейса.

Этот последний момент является основной причиной того, почему REST стал стандартным форматом для веб-API. Тщательно спроектированный набор конечных точек может одновременно обслуживать браузерный клиент, приложения для iOS и Android, а также интеграцию с внешними партнерами. Тщательная проработка этих конечных точек важна, поскольку от них зависит каждый клиент; в нашей статье ошибках в API-контракте, нарушающих надежность фронтенда рассматривается, что происходит, когда они не проработаны должным образом.

Почему REST по-прежнему является правильной отправной точкой

Существуют и другие подходы. GraphQL и gRPC, среди прочих, решают некоторые проблемы более изящно, чем REST — например, позволяют клиентам запрашивать именно те поля, которые им нужны, или обеспечивают эффективные вызовы между сервисами. Тем не менее REST остается лучшим выбором для начинающих по трём практическим причинам.

Во-первых, он встречается повсюду. Большинство публичных API, которыми вы, скорее всего, будете пользоваться — от поставщиков платежных услуг до сервисов метеоданных и социальных платформ, — предлагают интерфейс REST, часто в качестве стандартного. Ознакомившись с ним один раз, вы получаете универсальную модель, которую сможете использовать каждый раз при работе с незнакомой документацией.

Во-вторых, он соответствует собственной архитектуре веба. Методы HTTP и коды состояния были созданы не для REST; это протокол, который уже используют браузеры и серверы. Правильное изучение REST означает понимание того, как работает веб независимо от используемой фреймворки, и эти знания остаются актуальными долгое время, несмотря на изменения в конкретных библиотеках.

В-третьих, это естественный следующий шаг после освоения основ фронтенда. Как только вы уверенно владеете HTML, CSS и JavaScript, момент, когда интерфейс начинает загружать реальные данные вместо жестко заданных заменителей, обычно означает, что проект переходит от прототипа к чему-то, что люди действительно могут использовать. Для многих разработчиков, сосредоточенных на фронтенде, именно тогда создание собственного API перестает быть необязательным, и начинается путь к работе с полноценной стек-архитектурой. Если позже вы захотите подробно сравнить стили, ознакомьтесь с REST против GraphQL и особенности каждой архитектуры.

Создание вашего первого REST API с Node.js и Express

Чтение книг по этой теме помогает лишь до определенной степени. Всё становится ясно, как только вы что-то создадите, даже самую простую вещь. Типичный первый проект с Node.js и Express развивается по такой последовательности:

1. Создайте минимальный сервер, который прослушивает входящие HTTP-запросы на определенном порту.
2. Добавьте маршрут вроде /tasks и свяжите его с обработчиком GET, возвращающим список.
3. Добавьте обработчик POST на том же пути, который принимает новые задачи; на этом этапе достаточно хранить их в простом массиве в памяти.
4. Добавьте обработчики PUT (или PATCH) и DELETE, обычно на пути /tasks/:id, для обновления и удаления отдельных записей.
5. Как только структура API будет казаться подходящей, замените массив на настоящую базу данных.
6. Протестируйте каждый маршрут с помощью такого инструмента, как Postman, прежде чем подключать любой фронтенд.

Два фактора обеспечивают эффективность этой последовательности действий. Использование массива в памяти помогает сосредоточиться на маршрутах, методах и кодах состояния, а не на настройке базы данных. А последний шаг — тестирование маршрутов по отдельности — чаще всего игнорируется начинающими. Проверка API отдельно до того, как будет использоваться интерфейс, значительно упрощает отладку, поскольку не возникает вопросов о том, находится ли ошибка в самом API или в коде, который его вызывает.

По мере работы возвращайте соответствующие коды состояния, а не 200 для всего: 201, когда операция POST создает задачу, 404, когда идентификатор id отсутствует, 400, когда в теле запроса отсутствует обязательное поле. Именно такие небольшие решения делают API удобным для использования.

Где обычно терпят неудачу начинающие

Люди, которые испытывают трудности с REST, редко страдают от недостатка способностей. Они обычно застревают по предсказуемым, устраняемым причинам:

• Одновременное изучение концепций REST и фреймворка вроде Express, из-за чего невозможно понять, какие правила относятся к HTTP, а какие — к библиотеке.
• Отсутствие прямых тестов маршрутов с помощью инструментов вроде Postman, из-за чего ошибки фронтенда и бэкенда становятся неотличимыми.
• Игнорирование кодов состояния и механизмов обработки ошибок, что приводит к путанице, когда клиент не может отличить успех от неудачи.
• Переход к вопросам аутентификации до того, как будут полностью реализованы базовые маршруты для создания, чтения, обновления и удаления данных.
• Повторение API из учебного пособия дословно вместо создания простого приложения с другими ресурсами, что скрывает наличие понимания изложенных концепций.

Это проблемы структуры, а не таланта. Именно их решение обычно отличает тех, кто действительно умеет создавать бэкенд-API, от тех, кто может запомнить терминологию, но пока не умеет спроектировать конечную точку из пустого файла.

Адаптация под вашу текущую ситуацию

Основные принципы одинаковы для всех, но акценты меняются в зависимости от вашей ситуации.

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

Люди, меняющие карьеру, часто находят эти идеи более доступными, чем ожидалось; модель ресторана опирается на повседневный опыт, а не на техническую подготовку.

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

Привычки, помогающие усвоить концепции

Несколько привычек постоянно отличают тех, кто действительно понимает REST, от тех, кто лишь знает его название.

Создайте что-то небольшое и оригинальное, например список дел или API для заметок, вместо того чтобы просто читать документацию. Концепции становятся более устойчивыми, когда вам приходится отлаживать сломанный маршрут.

Научитесь диагностировать сбои вместо того, чтобы гадать. Прочитайте код состояния и сообщение об ошибке, определите, находится ли проблема с клиентской или серверной стороны, и подтвердите результат прямым запросом. На практике именно этот инстинкт важнее заученных определений, и именно он отличает того, кто создавал API, от того, кто лишь их использовал. По мере продвижения в профессии предоставление ошибок в едином, задокументированном формате облегчает диагностику для всех, кто использует ваш API.

Быстро получайте обратную связь. Способность спросить у опытного разработчика, коллеги или на форуме сообщества, почему запрос возвращает неверные данные, часто определяет успех первого проекта с API или его отказ. Длительное просмотрение видео без такой обратной связи — причина, по которой многие учащиеся теряют импульс к обучению.

Частые вопросы новичков

Что такое REST API, одним предложением?

Это набор конвенций, позволяющих приложениям взаимодействовать через Интернет с использованием стандартных HTTP-запросов и предсказуемых ответов.

Должны ли разработчики фронтенда изучать REST?

Да. Работа над фронтендом подразумевает постоянное использование REST-API, поэтому понимание этих принципов ожидается практически везде. Это также один из самых простых способов начать, если позже вы захотите перейти к разработке полноценных приложений.

Трудно ли изучить REST?

Основные идеи становятся понятными, когда их объясняют просто. Большинство трудностей связано с объяснениями, наполненными жаргоном, а не с самими концепциями.

Требуется ли диплом по информатике для создания бэкенд-API?

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

Можно ли изучить это, работая на полную ставку?

Да. Концепции просты, и достаточно небольшого проекта, созданного за несколько вечеров или выходных, чтобы сделать их понятными на практике.

Заключение

REST не такой уж и страшный, как может показаться по его репутации. Это единообразный способ для программного обеспечения запрашивать и передавать информацию, основанный на том же HTTP, который уже используется в интернете, и он лежит в основе большинства приложений, которыми вы пользуетесь каждый день.

• Пять ключевых идей составляют основу: ресурсы с URL, методы HTTP, запросы и ответы, коды состояния и отсутствие состояния.
• Сначала изучите концепции, а затем используйте Express для их практического применения.
• Проверяйте каждый маршрут отдельно, прежде чем от него будет зависеть фронтенд.
• Рассматривайте коды состояния и обработку ошибок как часть дизайна, а не как что-то, что добавляется в последнюю минуту.

Создайте что-то небольшое и оригинальное, а также научитесь диагностировать сбои вместо того, чтобы гадать.