Какие есть методы в REST API?

Методы REST API (HTTP методы)

REST (Representational State Transfer) использует стандартные HTTP методы (глаголы) для обозначения операций над ресурсами. Это основа RESTful архитектуры, которая делает API предсказуемым и согласованным.

Основные методы CRUD

Есть четыре основных HTTP метода, которые соответствуют операциям CRUD (Create, Read, Update, Delete):

1. GET — Получение данных (Read)

Используется для получения информации о ресурсе. GET запросы безопасны и идемпотентны (повторяющиеся вызовы дают одинаковый результат).

import requests

# Получить список всех пользователей
response = requests.get("https://api.example.com/users")
print(response.json())  # [{"id": 1, "name": "Alice"}, ...]

# Получить конкретного пользователя
response = requests.get("https://api.example.com/users/1")
print(response.json())  # {"id": 1, "name": "Alice"}

Характеристики:

• Безопасен (не изменяет данные)
• Идемпотентен
• Кешируется браузером
• Может содержать параметры в URL
• Статус код: 200 OK

2. POST — Создание данных (Create)

Используется для создания новых ресурсов. POST запросы НЕ идемпотентны — каждый вызов создаёт новый ресурс.

import requests
import json

# Создать нового пользователя
data = {"name": "Bob", "email": "bob@example.com"}
response = requests.post(
    "https://api.example.com/users",
    json=data
)
print(response.json())  # {"id": 2, "name": "Bob", "email": "..."}
print(response.status_code)  # 201 Created

Характеристики:

• Может изменять данные
• НЕ идемпотентен (каждый вызов = новый ресурс)
• Данные в теле запроса
• Статус код: 201 Created (или 200 OK)

3. PUT — Полное обновление (Update)

Используется для полного обновления ресурса. Требует отправить все поля ресурса. Идемпотентен — повторные вызовы с тем же данными дают одинаковый результат.

import requests

# Полностью обновить пользователя
data = {"id": 1, "name": "Alice Updated", "email": "alice_new@example.com"}
response = requests.put(
    "https://api.example.com/users/1",
    json=data
)
print(response.json())
print(response.status_code)  # 200 OK

Характеристики:

• Заменяет весь ресурс
• Идемпотентен
• Требует полный объект
• Статус код: 200 OK (или 204 No Content)

4. PATCH — Частичное обновление (Partial Update)

Используется для частичного обновления ресурса. Отправляете только изменяемые поля. Идемпотентен (в зависимости от реализации).

import requests

# Обновить только поле name
data = {"name": "Alice Modified"}
response = requests.patch(
    "https://api.example.com/users/1",
    json=data
)
print(response.json())
print(response.status_code)  # 200 OK

Характеристики:

• Обновляет только переданные поля
• Удобнее чем PUT
• Может быть идемпотентен
• Статус код: 200 OK

5. DELETE — Удаление (Delete)

Используется для удаления ресурса. Идемпотентен — повторное удаление несуществующего ресурса обычно возвращает 404 или 204.

import requests

# Удалить пользователя
response = requests.delete("https://api.example.com/users/1")
print(response.status_code)  # 204 No Content или 200 OK

Характеристики:

• Удаляет ресурс
• Идемпотентен
• Обычно нет тела ответа
• Статус код: 204 No Content (или 200 OK)

Дополнительные методы

HEAD — Как GET, но без тела

Получает метаинформацию без загрузки полного ответа.

# Проверить, существует ли ресурс
response = requests.head("https://api.example.com/users/1")
print(response.status_code)  # 200 если существует
print(dict(response.headers))  # Только заголовки, нет тела

OPTIONS — Доступные методы

Получает информацию о том, какие методы доступны для ресурса.

response = requests.options("https://api.example.com/users")
print(response.headers.get("Allow"))  # "GET, POST, PUT, DELETE"

Таблица всех методов

Практический пример REST API

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

users_db = [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"},
]

# GET — Получить всех пользователей
@app.get("/users")
def get_users():
    return users_db

# GET — Получить конкретного пользователя
@app.get("/users/{user_id}")
def get_user(user_id: int):
    return next(u for u in users_db if u["id"] == user_id)

# POST — Создать пользователя
@app.post("/users", status_code=201)
def create_user(user: User):
    users_db.append(user.dict())
    return user

# PUT — Полностью обновить пользователя
@app.put("/users/{user_id}")
def update_user(user_id: int, user: User):
    for i, u in enumerate(users_db):
        if u["id"] == user_id:
            users_db[i] = user.dict()
            return user
    return {"error": "User not found"}

# PATCH — Частично обновить пользователя
@app.patch("/users/{user_id}")
def partial_update(user_id: int, updates: dict):
    for u in users_db:
        if u["id"] == user_id:
            u.update(updates)
            return u
    return {"error": "User not found"}

# DELETE — Удалить пользователя
@app.delete("/users/{user_id}", status_code=204)
def delete_user(user_id: int):
    global users_db
    users_db = [u for u in users_db if u["id"] != user_id]

Статус коды

2xx — Успех:

• 200 OK — Успешный запрос
• 201 Created — Ресурс создан
• 204 No Content — Успешно, нет содержимого

4xx — Ошибка клиента:

• 400 Bad Request — Неверный запрос
• 401 Unauthorized — Требуется аутентификация
• 403 Forbidden — Доступ запрещен
• 404 Not Found — Ресурс не найден

5xx — Ошибка сервера:

• 500 Internal Server Error — Ошибка сервера

Лучшие практики

1. Используйте правильные методы:

   • GET для чтения
   • POST для создания
   • PUT/PATCH для обновления
   • DELETE для удаления

2. Возвращайте правильные статус коды

3. PATCH предпочтительнее PUT для частичных обновлений

4. Идемпотентность важна для отказоустойчивости

5. Документируйте API (используйте OpenAPI/Swagger)