Что такое API и почему он стал основой современной разработки
API (Application Programming Interface, программный интерфейс приложения) — это формальный договор между двумя программами о том, как они обмениваются данными. Одна сторона отправляет запрос в согласованном формате, а другая возвращает ответ, не раскрывая, как именно устроена её внутренняя логика. Именно эта «непрозрачность» делает API мощным инструментом: мобильное приложение может получать данные с сервера, ничего не зная о базе данных или языке, на котором написан бэкенд.
Сегодня почти любой цифровой продукт — это набор сервисов, общающихся через API. Когда вы оплачиваете покупку, ваше приложение вызывает API платёжной системы; когда смотрите прогноз погоды, приложение обращается к метеорологическому API. По оценкам отраслевых исследований, более 80% веб-трафика приходится не на страницы для людей, а на межмашинные вызовы API. Поэтому умение проектировать понятные и надёжные интерфейсы стало ключевой инженерной компетенцией.
Важно различать сам API как контракт и его реализацию. Хорошо спроектированный контракт живёт годами, переживая несколько переписываний внутреннего кода. Плохой контракт, наоборот, «протекает»: он навязывает клиентам детали внутренней структуры, и любое изменение на сервере ломает десятки приложений.
Архитектурный стиль REST: ресурсы и предсказуемость
REST (Representational State Transfer) — самый распространённый подход к построению веб-API. Его центральная идея проста: всё, чем оперирует система, представляется как ресурс с уникальным адресом. Пользователь, статья, заказ — каждый из них доступен по своему URL, например /users/42 или /articles/108. Действия над ресурсами описываются стандартными HTTP-методами.
Эта опора на существующие механизмы HTTP делает REST предсказуемым. Разработчик, впервые увидевший чужой REST-API, уже примерно понимает, как он работает, потому что соглашения одинаковы у большинства сервисов. GET читает данные и не должен их менять, POST создаёт новый ресурс, PUT и PATCH обновляют, DELETE удаляет. Коды состояния (200, 404, 500) тоже несут смысл, а не выбираются произвольно.
- GET /articles — получить список статей;
- GET /articles/108 — получить одну статью по идентификатору;
- POST /articles — создать новую статью;
- PATCH /articles/108 — частично обновить существующую статью;
- DELETE /articles/108 — удалить статью.
GraphQL: клиент сам решает, какие данные ему нужны
GraphQL — язык запросов к API, разработанный в компании Facebook и открытый в 2015 году. Его придумали как ответ на две типичные проблемы REST: избыточную выборку (over-fetching), когда сервер отдаёт лишние поля, и недостаточную выборку (under-fetching), когда для одного экрана приходится делать несколько запросов. В GraphQL клиент сам описывает, какие поля и связи ему нужны, и получает ровно их одним запросом.
Работает это через единственную точку входа и строгую схему типов. Схема описывает все доступные объекты и их поля, поэтому инструменты могут автоматически проверять запросы ещё до отправки на сервер. Для мобильных приложений с медленной сетью это большое преимущество: меньше запросов и меньше передаваемых данных означают более отзывчивый интерфейс.
Однако у гибкости есть цена. Кэшировать GraphQL сложнее, чем REST, потому что все запросы идут на один URL. Тяжёлый вложенный запрос может неожиданно нагрузить базу данных, поэтому нужны ограничения на глубину и сложность. GraphQL не заменяет REST, а дополняет его: он силён там, где данные сильно связаны и клиентам нужна разная их «нарезка».
REST против GraphQL: как выбирать
Выбор между подходами — это не вопрос моды, а вопрос характера задачи. Ниже сведены основные различия, которые стоит учитывать при проектировании нового сервиса. Ни один из вариантов не является «правильным» во всех случаях; зрелые команды нередко используют оба, разделяя ответственность между сервисами.
| Критерий | REST | GraphQL |
|---|---|---|
| Формат запроса | Много URL-адресов, HTTP-методы | Один URL, язык запросов |
| Выборка данных | Фиксирована сервером | Определяется клиентом |
| Кэширование | Простое, средствами HTTP | Требует отдельных решений |
| Кривая обучения | Пологая | Более крутая |
| Лучше всего для | Публичные, простые API | Сложные связанные данные |
Практическое правило: если API будет публичным и должен легко кэшироваться на уровне сети, начните с REST. Если приложение сложное, с множеством экранов, каждый из которых требует своей комбинации данных, GraphQL сэкономит время фронтенд-команде.
Версионирование: как менять API, не ломая клиентов
Как только вашим API начинают пользоваться сторонние приложения, вы теряете право свободно менять контракт. Удаление поля или переименование параметра может одномоментно сломать работу тысяч пользователей. Поэтому изменения делятся на обратно совместимые (добавление нового необязательного поля) и несовместимые (удаление или изменение семантики существующего).
Самый явный способ управлять несовместимыми изменениями — версионирование. Часто версию включают прямо в путь: /v1/articles и /v2/articles сосуществуют, пока старые клиенты не мигрируют. Альтернатива — передавать версию в заголовке запроса. Главное правило — никогда не менять поведение уже опубликованной версии молча.
Хорошая практика — политика устаревания (deprecation). Вы заранее объявляете, что версия перестанет поддерживаться через, скажем, шесть месяцев, помечаете устаревшие поля в документации и предупреждаете разработчиков. Это даёт командам-потребителям время спокойно перейти на новую версию без авралов.
Безопасность и аутентификация
API открывает доступ к данным, а значит становится мишенью для злоумышленников. Первый рубеж — аутентификация: сервер должен понимать, кто именно отправил запрос. Для этого чаще всего используют токены. Стандарт OAuth 2.0 позволяет приложению получить ограниченный доступ от имени пользователя, не раскрывая его пароль, а формат JWT (JSON Web Token) удобно переносит подписанные сведения о владельце.
После аутентификации идёт авторизация — проверка, что этому пользователю разрешено именно это действие. Частая уязвимость возникает, когда сервер проверяет, что человек вошёл в систему, но забывает проверить, что запрошенный ресурс принадлежит именно ему. В результате, подставив чужой идентификатор в URL, злоумышленник читает чужие данные. Это одна из самых распространённых ошибок из списка OWASP API Security Top 10.
- всегда используйте HTTPS, чтобы данные и токены нельзя было перехватить;
- ограничивайте частоту запросов (rate limiting) против перебора и перегрузки;
- проверяйте и «очищайте» все входные данные, не доверяя клиенту;
- выдавайте минимально необходимые права доступа, а не «всё сразу».
Документация и удобство для разработчика
API хорош ровно настолько, насколько легко его понять другому инженеру. Даже безупречно спроектированный интерфейс останется невостребованным, если к нему нет ясной документации. Отраслевым стандартом стала спецификация OpenAPI (ранее известная как Swagger): она в машиночитаемом виде описывает все эндпоинты, параметры и форматы ответов.
Из спецификации OpenAPI автоматически генерируются интерактивная документация, клиентские библиотеки на разных языках и наборы тестов. Разработчик может прямо в браузере отправить пробный запрос и увидеть ответ, не написав ни строчки кода. Такой подход, когда контракт описывается раньше реализации, называют «design-first» — сначала договор, потом код.
Помимо формального описания важны продуманные сообщения об ошибках. Ответ вида «400 Bad Request» без пояснений раздражает; ответ, который указывает, какое именно поле не прошло проверку и почему, экономит часы отладки. Забота о разработчике-потребителе (developer experience) — такая же часть проектирования, как и выбор структуры данных.
Типичные ошибки и практические советы
Начинающие инженеры часто проектируют API «изнутри наружу», просто открывая наружу структуру своих таблиц в базе данных. Это привязывает клиентов к деталям хранения и делает любую реорганизацию болезненной. Правильнее идти «снаружи внутрь»: сначала подумать, какие сценарии решает клиент, и спроектировать интерфейс под них, скрыв внутреннюю кухню.
Другая распространённая проблема — непоследовательность. Если в одном месте поле называется userId, в другом user_id, а в третьем uid, разработчики постоянно спотыкаются. Единые соглашения об именах, форматах дат (лучше всего ISO 8601) и структуре ошибок стоит зафиксировать в едином руководстве по стилю ещё до написания первого эндпоинта.
Наконец, не забывайте о пагинации и лимитах. Эндпоинт, который возвращает «все записи», рано или поздно попытается отдать миллион строк и уронит сервер. Разбивка ответа на страницы, разумные значения по умолчанию и явные ограничения на объём выборки — признаки зрелого, промышленного API, готового к росту нагрузки.
Источники
- Roy Fielding — автор диссертации, в которой был сформулирован архитектурный стиль REST.
- OpenAPI Initiative — организация, поддерживающая спецификацию OpenAPI (Swagger).
- OWASP Foundation — проект OWASP API Security Top 10 о типичных уязвимостях программных интерфейсов.
