0Pricing
AI Agents · Урок

Основы REST API для разработчиков агентов

Методы HTTP, коды состояния, заголовки и формат запросов и ответов JSON.

«Основы REST API для разработчиков агентов» — бесплатный урок AI Agents на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.

Что такое HTTP-запрос

Каждый агент, подключающийся к внешнему сервису, использует HTTP — язык веба. HTTP-запрос состоит из трёх ключевых частей: метода, URL и необязательных заголовков и тела.

Представляйте метод как глагол, сообщающий серверу, что вы хотите сделать, а URL — как адрес ресурса.

import requests

# A simple GET request to a public API
response = requests.get('https://api.example.com/users')
print(response.status_code)  # 200
print(response.text)          # raw JSON string

GET — получение данных

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

Параметры можно передавать в URL в виде строки запроса, используя аргумент params.

import requests

# Fetch users filtered by role
params = {'role': 'admin', 'page': 1, 'limit': 10}
response = requests.get(
    'https://api.example.com/users',
    params=params
)
# URL becomes: /users?role=admin&page=1&limit=10
data = response.json()
print(data['users'])

POST — создание ресурсов

POST отправляет данные на сервер для создания нового ресурса. Агенты используют POST для отправки задач, сообщений или запуска действий. Данные передаются в теле запроса в формате JSON.

Всегда задавайте заголовок Content-Type: application/json — большинство API этого требует.

import requests
import json

payload = {
    'title': 'Research competitors',
    'assignee': 'agent-001',
    'priority': 'high'
}

response = requests.post(
    'https://api.example.com/tasks',
    json=payload  # sets Content-Type automatically
)
print(response.status_code)  # 201 Created
new_task = response.json()
print('Created task ID:', new_task['id'])

PUT и PATCH — обновление данных

PUT заменяет весь ресурс новыми данными. PATCH обновляет только определённые поля. Агенты используют PUT, когда у них есть полностью обновлённый объект, а PATCH — для частичных изменений, например для обновления статуса задачи.

import requests

task_id = '42'

# PATCH: only update the status field
response = requests.patch(
    f'https://api.example.com/tasks/{task_id}',
    json={'status': 'completed'}
)
print(response.status_code)  # 200

# PUT: replace the whole task object
full_task = {
    'title': 'Research competitors',
    'assignee': 'agent-001',
    'priority': 'low',
    'status': 'completed'
}
response = requests.put(
    f'https://api.example.com/tasks/{task_id}',
    json=full_task
)
print(response.status_code)  # 200

DELETE — удаление ресурсов

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

Успешный delete обычно возвращает 204 No Content — в ответе нет тела.

import requests

task_id = '42'

response = requests.delete(
    f'https://api.example.com/tasks/{task_id}'
)

if response.status_code == 204:
    print('Task deleted successfully')
elif response.status_code == 404:
    print('Task not found — already deleted?')
else:
    print('Unexpected status:', response.status_code)

Коды состояния: успешные ответы 2xx

Коды состояния сообщают вашему агенту, успешно ли выполнен запрос. Диапазон 2xx означает успешное выполнение:

  • 200 OK — GET/PUT/PATCH вернули данные
  • 201 Created — POST создал новый ресурс
  • 204 No Content — DELETE выполнен успешно, тело не возвращено

Всегда проверяйте код состояния перед обработкой тела ответа.

import requests

response = requests.post(
    'https://api.example.com/tasks',
    json={'title': 'New task'}
)

if response.status_code == 201:
    task = response.json()
    print('Created:', task['id'])
elif response.status_code == 200:
    print('Updated existing resource')
else:
    print('Unexpected code:', response.status_code)

Коды состояния: ошибки клиента 4xx

Ошибки 4xx означают, что ваш агент отправил некорректный запрос. Распространённые варианты:

  • 400 Bad Request — некорректный JSON или отсутствует обязательное поле
  • 401 Unauthorized — отсутствует или недействителен ключ API
  • 404 Not Found — ресурс не существует
  • 429 Too Many Requests — превышен лимит запросов

В таких случаях агент должен исправить запрос, а не бездумно повторять его.

import requests

response = requests.get(
    'https://api.example.com/tasks/9999',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

if response.status_code == 401:
    print('AUTH ERROR: Check your API key')
elif response.status_code == 404:
    print('Task not found')
elif response.status_code == 429:
    retry_after = response.headers.get('Retry-After', 60)
    print(f'Rate limited. Wait {retry_after}s')
elif response.status_code == 400:
    print('Bad request:', response.json().get('error'))

Коды состояния: ошибки сервера 5xx

Ошибки 5xx означают, что проблема возникла на стороне сервера — ваш агент не сделал ничего неправильного. Распространённые варианты:

  • 500 Internal Server Error — ошибка или сбой сервера
  • 502 Bad Gateway — сбой вышестоящего сервиса
  • 503 Service Unavailable — сервер перегружен или недоступен

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

import requests
import time

def get_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code < 500:
            return response  # success or client error
        wait = 2 ** attempt
        print(f'Server error {response.status_code}, retrying in {wait}s...')
        time.sleep(wait)
    return response  # return last response after retries

Заголовки запроса

Заголовки передают метаданные с каждым запросом. Наиболее важные из них для агентов:

  • Content-Type: application/json — сообщает серверу, что тело запроса содержит JSON
  • Authorization: Bearer TOKEN — аутентифицирует запрос
  • Accept: application/json — сообщает серверу, что вы ожидаете получить JSON
  • User-Agent — идентифицирует ваш клиент (некоторые API требуют этот заголовок)
import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-proj-abc123xyz',
    'Accept': 'application/json',
    'User-Agent': 'MyAgent/1.0'
}

response = requests.post(
    'https://api.example.com/analyze',
    headers=headers,
    json={'text': 'Analyze this document'}
)

print(response.json())

Тело запроса и ответа в формате JSON

Большинство современных API обмениваются данными в формате JSON. При отправке используйте json=payload в запросах — это автоматически выполняет сериализацию и задаёт заголовки. При получении вызовите response.json(), чтобы преобразовать тело в словарь Python.

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

import requests

# Send JSON body
response = requests.post(
    'https://api.example.com/summarize',
    json={
        'content': 'Long article text here...',
        'max_length': 150,
        'format': 'bullet_points'
    }
)

# Parse JSON response
result = response.json()

# Always check keys exist
summary = result.get('summary', 'No summary returned')
tokens_used = result.get('usage', {}).get('total_tokens', 0)

print('Summary:', summary)
print('Tokens used:', tokens_used)

Собираем всё вместе

Хорошо написанный агент оборачивает вызовы API в чистую вспомогательную функцию, которая выбирает метод, задаёт правильные заголовки, проверяет код состояния и разбирает JSON. Благодаря этому каждое взаимодействие с API становится единообразным и его легко отлаживать.

Используйте объект Session, чтобы повторно использовать соединения и совместно применять заголовки в нескольких запросах.

import requests

class APIClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        })

    def get(self, path, params=None):
        r = self.session.get(f'{self.base_url}{path}', params=params)
        r.raise_for_status()
        return r.json()

    def post(self, path, payload):
        r = self.session.post(f'{self.base_url}{path}', json=payload)
        r.raise_for_status()
        return r.json()

# Usage
client = APIClient('https://api.example.com', 'sk-proj-abc123')
tasks = client.get('/tasks', params={'status': 'open'})
new_task = client.post('/tasks', {'title': 'Write report'})

Быстрая проверка: методы HTTP

Проверьте, насколько хорошо вы поняли методы HTTP и коды состояния.

Итоги основ HTTP

Теперь вы знаете основу HTTP, на которую опирается каждый агент:

  • GET получает данные, POST создаёт, PUT/PATCH обновляет, DELETE удаляет
  • 2xx = успех, 4xx = ошибка вашего агента, 5xx = ошибка сервера
  • Заголовки передают данные для аутентификации (Authorization: Bearer) и формат (Content-Type: application/json)
  • Используйте response.json(), чтобы разобрать тело, и .get(), чтобы безопасно получать значения полей
  • Объект Session совместно использует заголовки и соединения в разных запросах

Освоив эти основы, вы сможете уверенно подключать своего агента к любому REST API.

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

Урок «Основы REST API для разработчиков агентов» бесплатный?

Да — полный текст урока «Основы REST API для разработчиков агентов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.

Чему я научусь в уроке «Основы REST API для разработчиков агентов»?

Методы HTTP, коды состояния, заголовки и формат запросов и ответов JSON. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Agents?

Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Основы REST API для разработчиков агентов»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Agents?

Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Основы REST API для разработчиков агентов
  2. Аутентификация: ключи API и OAuth
  3. Обработка ответов API и ошибок
  4. Ограничение частоты запросов и логика повторных попыток
← Назад к AI Agents