Шаг 5 – Проектирование и реализация REST API (GET, POST, PUT, DELETE)

PUT-запросы

В типичной архитектуре REST клиент отправляет серверу запросы в виде методов HTTP для создания, извлечения, изменения или уничтожения ресурсов. Хотя и PUT, и POST могут использоваться для создания ресурсов, между ними есть существенные различия с точки зрения их предполагаемого применения.

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

С другой стороны, следует использовать метод PUT, чтобы запросить у сервера сохранение вложенного объекта под предоставленным URL. Если URL указывает на существующий ресурс на сервере, предоставленный объект будет считаться измененной версией существующего ресурса. Следовательно, вызов метода PUT либо создаст новый ресурс, либо обновит существующий.

Другое важное различие между методами заключается в том, что PUT является идемпотентным методом, а POST — нет. Например, многократный вызов метода PUT либо создаст, либо обновит один и тот же ресурс. Напротив, несколько запросов POST приведут к созданию одного и того же ресурса несколько раз.

В скелете нашего API нас уже есть функция, которая принимает PUT запросы, принимая message_id из параметра пути и сам текст записи. Метод мы объявили с помощью декоратора @app.put.

Давайте создадим метод для обработки процесса обновления существующей записи:

@app.put("/message/{message_id}")
async def update_message(message_id: str, message: str = Body()) -> str:
    messages_db[message_id] = message
    return f"Message updated!"

Функция update_message обернута в декоратор PUT запросов, и принимает переменную message_id из параметра пути и переменную message из самого тела запроса используя класс Body. Далее мы в нашей БД(словарь) находим запись с нужным message_id и меняем его значение из переменной message. Параметр status_code мы заполнять не будем, так как при успешном выполнении метод PUT возвращает код ответа 200.

Запустим приложение через команду uvicorn crud:app --port 8000 --reload и проверим работу. Зайдем в документацию, и попробуем отправить PUT запрос:

Изменим запись с id=0, и намнем Execute. Мы увидим команду curl, в которой текст записи был отправлен с помощью метода PUT внутри тела запроса.

curl -X 'PUT' \
  'http://127.0.0.1:8000/message/0' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '"The modified first message in FastAPI"'

И теперь если мы получим все записи, то как мы видим текст записи был изменен.

Попробуем изменить запись с id, которого не существует в нашей БД(словаре).

После отправки запроса мы увидим следующую команду curl:

curl -X 'PUT' \
  'http://127.0.0.1:8000/message/10' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '"Testing the PUT method to create a message"'

Теперь получим все записи через метод GET, и мы увидим что запись была успешно создана с помощью PUT запроса.

На этом мы закончим рассмотрение PUT запросов, в следующем шаге мы рассмотрим DELETE запросы, с помощью которых мы сможем удалять записи.