Что такое PUT запрос?

Общее определение PUT запроса

PUT (от англ. "положить") — это один из ключевых HTTP-методов (или HTTP-глаголов), используемых в архитектуре RESTful API. Семантика метода определена в стандарте HTTP/1.1 (RFC 7231). Основное предназначение PUT — полная замена (обновление) ресурса по указанному URI (Uniform Resource Identifier). Если ресурс по данному URI не существует, PUT-запрос часто должен его создать (идемпотентное создание), хотя это поведение может зависеть от реализации API.

В контексте мобильной разработки под iOS, мы постоянно работаем с сетевыми запросами, используя URLSession, Alamofire или другие библиотеки. Понимание нюансов каждого метода, включая PUT, критически важно для корректного взаимодействия с бэкендом.

Ключевые характеристики PUT запроса

1. Идемпотентность: Это самое важное свойство. Несколько идентичных PUT-запросов должны оказывать на сервер тот же эффект, что и один запрос. Отправив запрос на обновление email пользователя на "new@email.com" десять раз подряд, мы в итоге получим тот же результат, что и после одного запроса — email будет "new@email.com". Это отличает PUT от неидемпотентного POST.

2. Полная замена ресурса: Клиент отправляет полное представление ресурса, которое должно заменить существующее на сервере. Это значит, что если у объекта есть поля A, B и C, то в теле PUT-запроса необходимо передать значения для всех этих полей, даже если изменилось только одно из них. Непереданные поля могут быть интерпретированы как null и перезаписаны.

   // Исходный ресурс /users/123
   {
     "id": 123,
     "name": "Иван",
     "email": "old@email.com",
     "age": 30
   }
   
   // PUT запрос на /users/123 (меняем только email)
   {
     "id": 123,
     "name": "Иван", // ОБЯЗАТЕЛЬНО передаем повторно!
     "email": "new@email.com",
     "age": 30 // ОБЯЗАТЕЛЬНО передаем повторно!
   }
   

3. Создание ресурса: Если ресурс по указанному URI не существует и клиент имеет на это права, сервер может создать ресурс с предоставленными данными. При этом клиент указывает итоговый URI ресурса. Это поведение не всегда желательно, и часто создание делегируют методу POST.

PUT vs PATCH vs POST

Это классический вопрос, и понимание разницы — признак грамотного разработчика.

• PUT: "Замени ресурс целиком этим новым представлением." Идемпотентный.
• PATCH: "Частично обнови ресурс, применив эти изменения." Отправляется только измененная часть (например, в формате JSON Patch). Может быть неидемпотентным.
• POST: "Обработай эти данные согласно логике ресурса." Используется для создания (когда URI определяет сервер) или выполнения любых действий, не вписывающихся в CRUD. Неидемпотентный.

Пример использования PUT в iOS (Swift)

Рассмотрим пример обновления профиля пользователя с помощью нативного URLSession.

struct UserProfile: Codable {
    let id: Int
    var name: String
    var email: String
}

func updateUserProfile(_ profile: UserProfile, completion: @escaping (Result<UserProfile, Error>) -> Void) {
    // 1. Формируем URL
    guard let url = URL(string: "https://api.example.com/users/\(profile.id)") else {
        completion(.failure(URLError(.badURL)))
        return
    }

    // 2. Создаем URLRequest и настраиваем как PUT
    var request = URLRequest(url: url)
    request.httpMethod = "PUT" // Указываем метод
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    // 3. Кодируем модель в JSON для тела запроса
    do {
        let jsonData = try JSONEncoder().encode(profile)
        request.httpBody = jsonData
    } catch {
        completion(.failure(error))
        return
    }

    // 4. Создаем и запускаем data task
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // Обработка ошибок сети
        if let error = error {
            completion(.failure(error))
            return
        }

        // Проверка HTTP-статуса (ожидаем 200 OK или 204 No Content)
        guard let httpResponse = response as? HTTPURLResponse,
              (200...299).contains(httpResponse.statusCode) else {
            // Обработка ошибок сервера (4xx, 5xx)
            completion(.failure(URLError(.badServerResponse)))
            return
        }

        // Декодирование ответа (если сервер возвращает обновленный ресурс)
        if let data = data {
            do {
                let updatedProfile = try JSONDecoder().decode(UserProfile.self, from: data)
                completion(.success(updatedProfile))
            } catch {
                completion(.failure(error))
            }
        } else {
            // Если тело ответа пустое (статус 204)
            completion(.success(profile))
        }
    }
    task.resume()
}

Аналогичный запрос с использованием Alamofire (популярная сторонняя библиотека):

import Alamofire

AF.request("https://api.example.com/users/\(profile.id)",
           method: .put,
           parameters: profile,
           encoder: JSONParameterEncoder.default)
    .validate(statusCode: 200..<300)
    .responseDecodable(of: UserProfile.self) { response in
        switch response.result {
        case .success(let updatedProfile):
            print("Профиль обновлен: \(updatedProfile)")
        case .failure(let error):
            print("Ошибка: \(error.localizedDescription)")
        }
    }

Практические аспекты для iOS-разработчика

1. Согласование с бэкендом: Всегда сверяйся с документацией API. Некоторые бэкенды используют PUT для частичного обновления (как PATCH), что является отклонением от стандарта, но встречается на практике.
2. Кэширование: Ответы на успешные PUT-запросы обычно не кэшируются. Кроме того, успешный PUT-запрос должен инвалидировать кэшированные представления данного ресурса для GET и HEAD запросов.
3. Безопасность: PUT, как и другие методы, изменяющие данные, должен быть защищен (аутентификация, авторизация, HTTPS).
4. Обработка ошибок: Важно корректно обрабатывать возможные ответы сервера: 400 Bad Request (невалидные данные), 404 Not Found (ресурс не существует), 409 Conflict (состояние ресурса конфликтует с запросом) и т.д.

Итог: В iOS-разработке PUT-запрос — это стандартный инструмент для операции полного обновления ресурса в RESTful API. Его правильное использование, основанное на принципах идемпотентности и полного замещения, делает код предсказуемым, соответствует ожиданиям backend-разработчиков и облегчает поддержку приложения. Выбор между PUT, PATCH и POST — это сознательный дизайнерский выбор, влияющий на ясность и надежность API.