Making PUT requests to Atom collections

A web client can edit an existing Atom entry in a collection by making an HTTP PUT request to the URL of the Atom entry, as stated in the <atom:link rel="edit"> element of the entry.

About this task

You can only edit a single Atom entry at a time, using the URL of the individual Atom entry. You cannot edit multiple Atom entries in a single request. CICS® rejects PUT requests made to the URL of a collection.

Procedure

  1. Make an HTTP GET request to the URL of the Atom entry, as stated in the <atom:link rel="edit"> element of the entry, to retrieve a current copy of the entry and to obtain its entity tag from the ETag HTTP header on the response.
    Making GET requests to Atom feeds or collections explains how to do this.
  2. Begin your HTTP PUT request with a request line consisting of the PUT method, followed by the path component of the URL of the Atom entry, followed by HTTP/1.1, which is the HTTP version for the request.
    You may also include the scheme (HTTP or HTTPS) and the host name in the URL.
  3. Write HTTP headers for the request as follows, each on a new line:
    • The Host header, giving the host name from the URL of the Atom entry, if you did not already include the host name in the request line.
    • The Authorization header, with any security information required to access your collection, such as a user ID and password for basic authentication.
    • The If-Match header, with the entity tag that you just obtained for the existing Atom entry. If you have to override this check, you may use an asterisk in place of an entity tag, which makes the server apply your edits to the Atom entry even if it has been changed by another agent since you obtained it. Use this option with caution.
    • The Content-Type header, with the value application/atom+xml;type=entry.
    • The Content-Length header, stating the length of your message body in bytes (octets). Specify the value for this header when you have finished writing the message body.
    Put an additional carriage return line feed (CRLF) after the last HTTP header to give an empty line.
  4. Copy the Atom entry into your message body, and add the element <?xml version="1.0" ?> before it.
    Check that the <entry> tag contains the namespace declaration xmlns="http://www.w3.org/2005/Atom".
  5. Edit the content of the elements in the Atom entry that you want to change.
    CICS provides correct time stamps, and a service routine must do the same, so do not update the time stamps in the entry.
    For a description of the content of each element, see <atom:entry> Atom configuration file element.
  6. Send your request to the server.

Results

When your request is accepted, the server sends an HTTP response with the status code 200, indicating successful completion of the request, or a suitable error response. CICS returns a copy of the edited Atom entry as the body of the response, so that you can verify your changes if you want.

As for a POST request, if you receive an error response, read the message body for the response, and refer to the list of status codes that CICS provides to web clients in HTTP status code reference for CICS web support. For an error response that might indicate a problem with your request, check for message DFHML0100 from the CICS region, and consult the z/OS XML System Services User's Guide and Reference for an explanation of the return code and reason code.

Example

This is an HTTP PUT request to edit the Atom entry with the URL http://www.example.com:80/web20/entry/10 :
PUT /web20/entry/10 HTTP/1.1
Host: www.example.com:80
Content-Type: application/atom+xml;type=entry
Content-Length: 1034
If-Match: c4826af12991fb102ef13099c927c2ac24e4caa2

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
    <generator uri="http://www.ibm.com/cics/" version="6.6.0">
    CICS Transaction Server Version 4.1.0
    </generator>
    <link rel="self" href="http://www.example.com:80/web20/entry/10"/>
    <link rel="edit" href="http://www.example.com:80/web20/entry/10"/>
    <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:10</id>
    <title>This is my updated entry</title>
    <summary>
    This is my new updated entry
    </summary>
    <category term="Test Feeds"/>
    <rights>Copyright (c) 2009, Joe Bloggs</rights>
    <published>2009-04-23T15:00:44+00:00</published>
    <author>
    	<name>Joe Bloggs</name>
    	<email>JBloggs@example.com</email>
    	<uri>http://www.example.com/JBloggs/</uri>
    </author>
    <app:edited>2009-04-23T15:00:44+00:00</app:edited>
    <updated>2009-04-23T15:00:44+00:00</updated>
    <content type="text/xml">
	    <SAMPBIND xmlns="http://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
	    	<data_field>
	    	 Here is new content for my updated entry
	    	</data_field>
    	</SAMPBIND>
    </content>
</entry>