Request():put()
Execute a PUT request and return a Response object. This method is used to completely replace a resource on a server.
Signature
put(): Response
Returns
Response
- The response object containing the server response
Description
The put()
method sends an HTTP PUT request to the URL specified when creating the Request object. PUT requests are typically used to completely replace existing resources with new data, or to create a resource at a specific URL.
Use setParameter()
to add data to the request body before calling put()
.
Examples
Basic PUT Request
-- Replace a user's complete data
local response = Request("https://api.example.com/users/123")
:setParameter("name", "John Smith")
:setParameter("email", "john.smith@example.com")
:setParameter("age", "35")
:setParameter("status", "active")
:put()
PUT Request with JSON Headers
-- Replace an entire post with new content
local response = Request("https://api.example.com/posts/456")
:setHeader("Content-Type", "application/json")
:setHeader("Authorization", "Bearer your-token-here")
:setParameter("title", "Completely New Title")
:setParameter("body", "Completely new post content")
:setParameter("userId", "1")
:setParameter("status", "published")
:put()
Processing PUT Response
-- Update user profile and handle response
local response = Request("https://api.example.com/users/789")
:setHeader("Content-Type", "application/json")
:setHeader("Authorization", "Bearer token123")
:setParameter("name", "Jane Doe")
:setParameter("email", "jane.doe@example.com")
:setParameter("bio", "Software Developer")
:setParameter("website", "https://jane.example.com")
:setParameter("location", "San Francisco")
:put()
local data = response:getData()
local statusCode = response:getResponseCode()
if statusCode == 200 then
print("User updated successfully!")
print("Updated user data: " .. data)
elseif statusCode == 201 then
print("User created successfully!")
print("New user data: " .. data)
else
print("Failed to update user. Status: " .. statusCode)
end
PUT for Resource Creation
-- Create a new resource at a specific URL
local response = Request("https://api.example.com/files/document-v2")
:setHeader("Content-Type", "application/json")
:setParameter("content", "This is the new document content")
:setParameter("version", "2.0")
:setParameter("author", "John Doe")
:put()
local status = response:getResponseCode()
if status == 201 then
print("Document created successfully!")
elseif status == 200 then
print("Document replaced successfully!")
else
print("Operation failed with status: " .. status)
end
Conditional PUT Update
-- Update only if resource hasn't been modified
local response = Request("https://api.example.com/articles/123")
:setHeader("Content-Type", "application/json")
:setHeader("If-Match", "etag-value-here")
:setHeader("Authorization", "Bearer token")
:setParameter("title", "Updated Article Title")
:setParameter("content", "Updated article content")
:setParameter("author", "John Doe")
:put()
local status = response:getResponseCode()
if status == 412 then
print("Update failed: Resource has been modified by another user")
elseif status == 200 or status == 201 then
print("Article updated/replaced successfully")
end
Complete Resource Replacement
-- Replace an entire product with new data
local response = Request("https://api.example.com/products/456")
:setHeader("Content-Type", "application/json")
:setParameter("name", "Premium Widget")
:setParameter("description", "A high-quality widget with advanced features")
:setParameter("price", "99.99")
:setParameter("stock", "50")
:setParameter("category", "electronics")
:setParameter("specs", '{"color": "black", "weight": "200g", "warranty": "2 years"}')
:put()
local updatedProduct = response:getData()
print("Product replaced: " .. updatedProduct)
Notes
- Use
setParameter()
to add data to the request body before callingput()
- PUT requests should contain the complete representation of the resource, not just the changes
- PUT is different from PATCH in that PUT replaces the entire resource, while PATCH makes partial updates
- Successful PUT operations typically return:
200 OK
with the updated resource in the response body (for updates)201 Created
with the new resource in the response body (for creation)204 No Content
if the operation was successful but no response body is needed
- The method returns a Response object which you can use to access the response data and status code
- Always check the response status code to ensure the request was successful
- PUT requests are idempotent - making the same request multiple times should have the same effect
- Be careful when using PUT requests as they completely replace existing data