REST API: что это такое, как работает и как отправить первый запрос

REST API помогает программам обмениваться данными по HTTP: у каждого объекта свой адрес, а действие задаёт метод GET, POST, PUT или DELETE.

Разбираем шесть принципов REST, методы и коды ответов, поднимаем учебный сервер на Python и отправляем ему запросы через curl с реальным выводом.

Статью написал:
Ваня Буявец, продюсер, основатель Checkroi
Ваня Буявец
Основатель Checkroi, продюсер, эксперт в выборе онлайн-курсов
Все 3286 статей автора Подписаться на Телеграм-канал
Одобрено экспертом:
Наташа Буявец, основатель Checkroi, эксперт по онлайн-курсам
Наташа Буявец
Основательница Checkroi, продюсер Youtube-каналов, эксперт по онлайн-курсам
Все 3940 экспертных мнений Подписаться на Телеграм-канал
Обложка: REST API: что это такое, как работает и как отправить первый запрос

REST API — это способ, которым программы обмениваются данными через обычный HTTP. У каждого объекта на сервере есть свой адрес, например /tasks/1, а что с ним сделать, решает метод запроса: GET читает, POST создаёт, PUT заменяет, DELETE удаляет. Сервер отвечает кодом статуса и данными, чаще всего в формате JSON.

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

Что такое REST API простыми словами

Рой разбирается, как приложение обменивается данными с сервером

REST расшифровывается как Representational State Transfer, по-русски «передача состояния представления». Стиль описал Рой Филдинг в 2000 году в пятой главе своей диссертации. У него REST назван архитектурным стилем, то есть набором ограничений для системы. Поэтому скачать или установить REST нельзя: им пользуются, когда проектируют API.

API, который соблюдает эти ограничения, называют RESTful. В разговоре «REST API» и «RESTful API» почти всегда значат одно и то же.

Чтобы читать документацию к любому REST API, хватит пяти слов:

Термин Что значит Пример
Ресурс Объект, с которым работает API задача, пользователь, заказ
Эндпоинт Адрес ресурса или списка ресурсов /tasks, /tasks/1
Метод Что сделать с ресурсом GET, POST, PUT, PATCH, DELETE
Представление Как ресурс выглядит в ответе JSON-объект {"id": 1}
Код статуса Чем закончился запрос 200, 201, 404

Слово «представление» из расшифровки как раз про последнюю строку. Клиент никогда не получает сам объект из базы, только его копию в каком-то формате. Про формат подробно рассказали в статье что такое JSON.

Как работает REST-запрос

Путь одного запроса от приложения до сервера и обратно укладывается в четыре шага:

  1. Клиент собирает запрос: метод, адрес ресурса, заголовки и, если нужно, тело с данными.
  2. Запрос уходит по HTTP или HTTPS. Как устроен сам протокол, мы разбирали в материале про сетевые протоколы.
  3. Сервер находит ресурс по адресу и выполняет действие, которое задаёт метод.
  4. Сервер возвращает код статуса, заголовки и тело ответа.

Так выглядит обмен целиком, если убрать всё лишнее. Сверху запрос, снизу ответ:

GET /tasks/1 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1, "title": "Купить молоко", "done": false}

Посмотреть такие запросы живьём можно на любом сайте: откройте DevTools в браузере, перейдите на панель «Сеть» (в английском интерфейсе Network) и обновите страницу.

Канал основателя Checkroi Вани Буявца3 800 человек читают мой Телеграм-канал про нейросетиСобрал промпты для Claude Code и ChatGPT, разборы ИИ-инструментов и лайфхаки по продвижению бизнеса в одном местеПрисоединиться

Шесть принципов REST

Ноутбук и сервер на столе, между ними линии запросов

Филдинг собрал REST из шести ограничений. Пять обязательные, шестое он прямо назвал необязательным:

  1. Клиент-сервер. Интерфейс и хранение данных разделены. Мобильное приложение и сайт ходят в один и тот же API и ничего не знают о базе данных.
  2. Отсутствие состояния (stateless). Каждый запрос несёт всё, что нужно для ответа: адрес, параметры, токен. Сервер не помнит, о чём клиент спрашивал минуту назад.
  3. Кэширование. Ответ сам говорит, можно ли его сохранить и на сколько. Повторный запрос тогда не доходит до сервера.
  4. Единообразный интерфейс. Все ресурсы устроены одинаково: у каждого свой адрес, а работа идёт через представления и стандартные методы.
  5. Многоуровневая система. Между клиентом и сервером могут стоять прокси, балансировщики и кэши, а клиент их не замечает.
  6. Код по запросу. Сервер может прислать клиенту исполняемый код, например скрипт. Это единственное необязательное ограничение.

Четвёртый пункт у Филдинга раскрыт ещё на четыре требования: ресурсы опознаются по адресу, меняются через представления, сообщения описывают сами себя, а ссылки в ответе подсказывают клиенту следующий шаг. Последнее требование называют HATEOAS, и до него доходят немногие API.

На практике чаще всего важен второй принцип. Если API хранит у себя «текущий шаг» пользователя, его трудно масштабировать: второй сервер про этот шаг ничего не знает.

Методы HTTP в REST API

Метод отвечает за действие, поэтому адрес у ресурса один. /tasks/2 читается, заменяется и удаляется по одному и тому же URL.

Метод Что делает Пример Безопасный Идемпотентный
GET Читает ресурс или список GET /tasks да да
POST Создаёт новый ресурс POST /tasks нет нет
PUT Заменяет ресурс целиком PUT /tasks/2 нет да
PATCH Меняет часть полей PATCH /tasks/2 нет не гарантируется
DELETE Удаляет ресурс DELETE /tasks/2 нет да

Безопасный метод не меняет данные на сервере. По стандарту HTTP RFC 9110 безопасны GET, HEAD, OPTIONS и TRACE.

Идемпотентный метод при повторе даёт тот же результат, что и один раз. RFC 9110 относит к идемпотентным PUT, DELETE и все безопасные методы. Поэтому клиент может спокойно повторить PUT, если связь оборвалась, а повторный POST создаст дубль. Подробнее про это свойство рассказали в статье идемпотентность простыми словами, а разницу GET и POST мы разбирали в материале про методы HTTP.

Коды ответов, которые встречаются чаще всего

На код статуса программа-клиент смотрит первым делом. Первая цифра говорит о группе: 2xx означает успех, 4xx ошибку клиента, 5xx ошибку сервера.

Код Что значит Когда REST API его возвращает
200 OK Запрос выполнен GET, PUT, PATCH с данными в ответе
201 Created Создан новый ресурс успешный POST
204 No Content Выполнено, тела в ответе нет успешный DELETE
400 Bad Request Ошибка в запросе клиента нет обязательного поля, кривой JSON
401 Unauthorized Нет действующих учётных данных забыли токен или он истёк
403 Forbidden Доступ запрещён токен есть, а прав нет
404 Not Found Ресурс не найден запросили удалённую задачу
500 Internal Server Error Сбой на сервере ошибка в коде API

Определения взяты из раздела 15 RFC 9110. Как проверить код ответа любой страницы, показали в инструкции про коды ответов сервера.

CheckroiCheckroiПодборка курсов по REST110 курсов • 21 школаСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Как правильно называть адреса ресурсов

Строгого стандарта на адреса нет, но договорённости в индустрии устойчивые. Ресурс называют существительным во множественном числе, а действие оставляют методу.

Задача Так принято Так не надо
Получить список задач GET /tasks GET /getAllTasks
Получить одну задачу GET /tasks/7 GET /task?id=7&action=show
Удалить задачу DELETE /tasks/7 POST /tasks/7/delete
Задачи одного пользователя GET /users/5/tasks GET /userTasks?user=5
Только выполненные GET /tasks?done=true GET /tasks/done

Фильтры, сортировку и постраничный вывод передают в параметрах после знака «?». Версию API часто ставят в начало пути, например /v1/tasks: так старые клиенты не ломаются, когда выходит вторая версия.

Описание всех эндпоинтов обычно выкладывают в формате спецификации OpenAPI. По нему строится интерактивная документация, где запрос можно отправить прямо со страницы. Так устроены, например, документация REST API GitHub и API hh.ru.

Ваня БуявецКанал основателя Checkroi Вани БуявцаЗабирайте промпты и обучение по нейросетям в моём Телеграм-каналеБольше 3 800 человек уже применяют Claude Code, ChatGPT и другие нейросети в работе, учёбе, бизнесе и жизниПерейти в канал

Пример: REST API на Python за пять минут

Рой радуется, что его первый сервер ответил на запрос

Теория быстро забывается, поэтому поднимем свой сервер со списком задач. Понадобится только Python 3, внешние библиотеки не нужны. Если вы ещё не запускали ни одной программы, начните с инструкции как написать код на Python. Сохраните код в файл server.py:

import json
from http.server import BaseHTTPRequestHandler, HTTPServer

tasks = {1: {"id": 1, "title": "Купить молоко", "done": False}}
next_id = 2

class Handler(BaseHTTPRequestHandler):
    def send_json(self, status, data=None):
        body = b"" if data is None else json.dumps(data, ensure_ascii=False).encode()
        self.send_response(status)
        if data is not None:
            self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def task_id(self):
        parts = self.path.strip("/").split("/")
        if parts[0] != "tasks":
            return "bad"
        return int(parts[1]) if len(parts) == 2 and parts[1].isdigit() else None

    def read_body(self):
        size = int(self.headers.get("Content-Length", 0))
        return json.loads(self.rfile.read(size) or "{}")

    def do_GET(self):
        tid = self.task_id()
        if tid == "bad":
            return self.send_json(404, {"error": "not found"})
        if tid is None:
            return self.send_json(200, list(tasks.values()))
        if tid not in tasks:
            return self.send_json(404, {"error": "task not found"})
        self.send_json(200, tasks[tid])

    def do_POST(self):
        global next_id
        data = self.read_body()
        if "title" not in data:
            return self.send_json(400, {"error": "title is required"})
        task = {"id": next_id, "title": data["title"], "done": False}
        tasks[next_id] = task
        next_id += 1
        self.send_json(201, task)

    def do_PUT(self):
        tid = self.task_id()
        if tid not in tasks:
            return self.send_json(404, {"error": "task not found"})
        data = self.read_body()
        tasks[tid] = {"id": tid, "title": data.get("title"), "done": data.get("done", False)}
        self.send_json(200, tasks[tid])

    def do_DELETE(self):
        tid = self.task_id()
        if tid not in tasks:
            return self.send_json(404, {"error": "task not found"})
        del tasks[tid]
        self.send_json(204)

    def log_message(self, *args):
        pass

HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()

Запустите его командой python3 server.py и откройте второе окно терминала. Запросы отправим утилитой curl (справка по ключам команды), она есть в macOS и большинстве дистрибутивов Linux. Ниже вывод, снятый на Python 3.14.7 и curl 8.7.1.

Читаем задачу: GET

Флаг -i показывает заголовки ответа вместе с телом. Тело собирает метод send_json: он превращает словарь Python в строку функцией json.dumps, о ней подробнее в инструкции как записать данные в JSON в Python.

$ curl -i http://127.0.0.1:8000/tasks/1
HTTP/1.0 200 OK
Server: BaseHTTP/0.6 Python/3.14.7
Date: Sat, 14 Nov 2026 09:20:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 62

{"id": 1, "title": "Купить молоко", "done": false}

Создаём задачу: POST

Данные передаём в теле запроса и предупреждаем сервер заголовком, что это JSON. Сервер отвечает кодом 201 и возвращает созданную задачу уже с номером:

$ curl -i -X POST http://127.0.0.1:8000/tasks -H 'Content-Type: application/json' -d '{"title": "Позвонить маме"}'
HTTP/1.0 201 Created
Server: BaseHTTP/0.6 Python/3.14.7
Date: Sat, 14 Nov 2026 09:20:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 64

{"id": 2, "title": "Позвонить маме", "done": false}

$ curl http://127.0.0.1:8000/tasks
[{"id": 1, "title": "Купить молоко", "done": false}, {"id": 2, "title": "Позвонить маме", "done": false}]

Меняем и удаляем: PUT и DELETE

PUT присылает задачу целиком, с новым значением поля done. После DELETE тот же адрес отвечает кодом 404, потому что ресурса больше нет:

$ curl -X PUT http://127.0.0.1:8000/tasks/2 -H 'Content-Type: application/json' -d '{"title": "Позвонить маме", "done": true}'
{"id": 2, "title": "Позвонить маме", "done": true}

$ curl -i -X DELETE http://127.0.0.1:8000/tasks/2
HTTP/1.0 204 No Content
Server: BaseHTTP/0.6 Python/3.14.7
Date: Sat, 14 Nov 2026 09:20:22 GMT
Content-Length: 0

$ curl -i http://127.0.0.1:8000/tasks/2
HTTP/1.0 404 Not Found
Server: BaseHTTP/0.6 Python/3.14.7
Date: Sat, 14 Nov 2026 09:20:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 27

{"error": "task not found"}

Учебный сервер хранит задачи в памяти, и после перезапуска список снова начнётся с молока. Для боевого API модуль не годится: в документации Python прямо сказано, что http.server не рекомендуют для продакшена. Там берут фреймворки вроде FastAPI, Django REST Framework или Express, а данные кладут в базу.

REST, SOAP и GraphQL: в чём разница

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

REST SOAP GraphQL
Что это архитектурный стиль протокол W3C язык запросов
Формат обычно JSON только XML JSON
Адреса отдельный адрес на каждый ресурс обычно один адрес сервиса один эндпоинт
Кто решает, какие поля вернуть сервер сервер клиент
Где встречается публичные API, мобильные приложения банки, госсистемы, старые корпоративные системы сложные интерфейсы с множеством связанных данных

Про «RESTful» спорят часто, и тут полезна модель зрелости Ричардсона, которую описал Мартин Фаулер. В ней четыре уровня:

  • Уровень 0: HTTP служит просто транспортом, все вызовы идут на один адрес.
  • Уровень 1: появляются ресурсы со своими адресами.
  • Уровень 2: действие задают методы HTTP, а результат показывают коды статуса.
  • Уровень 3: ответы содержат ссылки на следующие действия, то есть HATEOAS.

Большинство API, которые называют себя RESTful, живут на втором уровне. Наш учебный сервер тоже.

Частые ошибки новичков

Эти ошибки не ломают API сразу, но потом стоят часов отладки на стороне клиента.

  • Глагол в адресе. /createTask и /deleteTask дублируют работу методов. Решение: один адрес /tasks и разные методы.
  • Ошибка с кодом 200. Сервер отвечает «200 OK», а в теле пишет {"error": "..."}. Клиент считает запрос успешным и падает дальше. Решение: отдавать 4xx или 5xx, как наш сервер отдаёт 400 на задачу без названия.
  • GET, который меняет данные. Браузеры, поисковые роботы и кэши считают GET безопасным и могут повторить его сами. Решение: всё, что меняет данные, отправлять через POST, PUT, PATCH или DELETE.
  • Повтор POST без защиты. Пользователь дважды нажал кнопку, и появилось две одинаковые задачи. Решение: ключ идемпотентности в заголовке или проверка дубля на сервере.
  • Состояние в памяти сервера. API запоминает «текущую страницу» клиента, и при втором сервере за балансировщиком всё рассыпается. Решение: передавать номер страницы и токен в каждом запросе.

Четвёртую ошибку легко увидеть на нашем сервере. Два одинаковых POST подряд создают две задачи:

$ curl -X POST http://127.0.0.1:8000/tasks -H 'Content-Type: application/json' -d '{"title": "Вынести мусор"}'
{"id": 3, "title": "Вынести мусор", "done": false}
$ curl -X POST http://127.0.0.1:8000/tasks -H 'Content-Type: application/json' -d '{"title": "Вынести мусор"}'
{"id": 4, "title": "Вынести мусор", "done": false}

Такие сценарии проверяет тестировщик-автоматизатор: API-тесты пишут именно на коды статуса, повторы и пустые поля.

Где освоить REST API системно

Отправить первый запрос можно за вечер. А чтобы спроектировать API для тысяч клиентов, нужны навыки бэкенд-разработчика: авторизация, версии, документация, тесты. С чего начать путь в профессию, мы описали в плане как стать backend-разработчиком.

Курсы, где REST API разбирают на практике, собраны в каталоге по навыку REST. Вот пять из них:

КурсШколаСтоимость со скидкойВ рассрочкуДлитель­ностьОбзор курса от Checkroi
Node.js. Профессиональная разработка REST API
Перейти на сайт курса
HTMLAcademyHTML Academy29 900 ₽9960 ₽/мес.2 месяцаОбзор курса
Профессия «Python-разработчик»
Перейти на сайт курса
SkillboxSkillbox157 335 ₽5987 ₽/мес.10 месяцевОбзор курса
PHP-разработчик. Базовый уровень
Перейти на сайт курса
SkillboxSkillbox81 167 ₽5227 ₽/мес.3 месяцаОбзор курса
Профессия «Системный аналитик с нуля до middle»
Перейти на сайт курса
НетологияНетология144 550 ₽6022 ₽/мес.15 месяцевОбзор курса
Системный аналитик с нуля: тариф PRO
Перейти на сайт курса
Академия ЭдюсонЭдюсон136 395 ₽5683 ₽/мес.6 месяцевОбзор курса

Больше программ — в полном каталоге курсов по REST

Часто задаваемые вопросы

Что такое REST API простыми словами?

Это договорённость, как программам обмениваться данными по HTTP. У каждого объекта есть свой адрес, например /tasks/1, а действие задаёт метод: GET читает, POST создаёт, PUT заменяет, DELETE удаляет. Ответ приходит с кодом статуса и обычно в формате JSON.

Как расшифровывается REST?

Это сокращение от Representational State Transfer, по-русски «передача состояния представления». Термин появился в диссертации Роя Филдинга 2000 года.

Чем REST API отличается от RESTful API?

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

Какие методы используются в REST API?

Основные пять: GET для чтения, POST для создания, PUT для полной замены, PATCH для частичного изменения и DELETE для удаления. GET безопасный, а GET, PUT и DELETE ещё и идемпотентные, их можно повторять без побочных эффектов.

Чем REST отличается от SOAP?

SOAP является протоколом со строгим форматом сообщений на XML и обычно одним адресом сервиса. REST описывает архитектурный стиль: отдельный адрес у каждого ресурса, стандартные методы HTTP и чаще всего JSON. SOAP до сих пор встречается в банках и госсистемах, REST чаще используют в публичных API и мобильных приложениях.

Как попробовать REST API без программирования?

Достаточно утилиты curl в терминале: команда curl -i и адрес эндпоинта покажут код статуса, заголовки и тело ответа. Ещё проще открыть DevTools в браузере, панель «Сеть», и посмотреть, какие запросы отправляет любой сайт.

Читайте Checkroi первым в Google
Добавьте Checkroi в избранные источники — и наши разборы курсов и обзоры школ будут показываться выше в вашей выдаче Google.
Оставить комментарий
0 комментариев
Форма комментария

Оставьте комментарий

Напишите, что думаете. Нам важно ваше мнение!