Making POST requests to Atom collections

A web client can create a new Atom entry in a collection by making an HTTP POST request to the URL of the collection.

Before you begin

If you do not know the URL of the collection that you want to edit, or you are writing an application that can handle multiple collections, first make an HTTP GET request for the Atom service document that you set up in Creating an Atom service document. The Atom service document lists the URLs of the collections that are available on the server.

Procedure

  1. Begin your HTTP POST request with a request line consisting of the POST method, followed by the path component of the URL of the collection, 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.
  2. 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 collection, 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 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.
  3. Set up a message body containing the XML markup for the Atom entry that you want to post.
    1. If you already have Atom entries in your collection, make a GET request to obtain a feed or entry document for the collection, and copy an existing Atom entry from the collection into your message body.
    2. If you do not have any Atom entries in your collection yet, write the XML markup for your first Atom entry based on the examples in these topics.
    3. Check that the <entry> tag at the start of your Atom entry contains the namespace declaration xmlns="http://www.w3.org/2005/Atom", and add that namespace declaration if it is not present. In Atom documents sent from CICS, the elements typically do not include the atom: namespace prefix. The Atom namespace is defined as the default namespace in the element at the beginning of the Atom document, so you do not have to use the atom: prefix for the child elements. In the CICS documentation, the prefix is used in the element names for clarity. If you prefer to use the atom: namespace prefix in the elements in your request, change the namespace declaration to xmlns:atom="http://www.w3.org/2005/Atom".
    4. Add the element <?xml version="1.0" ?> before your Atom entry.
  4. Specify the appropriate elements of your Atom entry with the data that you require, and delete any elements that you do not use. You do not need to provide data for all the elements that are present in an Atom entry document sent out by CICS. When you post an entry to a collection managed by CICS, you can omit any elements that are not stored in the CICS resource, and also any elements that are stored in the CICS resource but are generated by CICS or the service routine. Typically, you can omit at least the following elements:
    • Elements containing time stamps, such as the <atom:updated> element (unless your service routine accepts user input for these)
    • The <atom:id> element
    • The <atom:contributor> element
    • The <atom:link> element
    • The <atom:rights> element
    If in doubt, include the element, and CICS or the service routine will ignore it if it is not wanted. RFC 5023 has the complete list of possible elements in Atom entries. For a summary of the elements that are required, allowed, or not used in Atom entries, see Atom element reference for CICS. For a description of the content of each element, see <atom:entry> Atom configuration file element.
  5. Send your request to the server.

Results

The server sends an HTTP response with the status code 200, indicating successful completion of the request, or a suitable error response. If the request is successful, the response contains a copy of the new Atom entry. Check the Atom entry in the response from the server against your original submission, to make sure that you are satisfied with the new entry.

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. If the error response indicates that there might be a problem with your request, such as the HTTP status code 400 (Bad Request or Invalid Request), check to see whether the CICS region has issued message DFHML0100. CICS uses the z/OS XML System Services parser to parse the XML markup of your Atom entry. If the parser finds a problem with the markup, CICS issues message DFHML0100 containing the return code and reason code from the parser. For an explanation of the return code and reason code, see the z/OS XML System Services User's Guide and Reference.

Example

This is a request to create a new Atom entry in a collection with the URL http://www.example.com:80/web20/myfeed :
POST /web20/myfeed HTTP/1.1
Host: www.example.com:80
Content-Type: application/atom+xml;type=entry
Content-Length: 763

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <title>This is my posted entry</title>
    <summary>
    This is my new posted entry
    </summary>
    <category term="Test Feeds"/>
    <author>
    	<name>Joe Bloggs</name>
    	<email>JBloggs@example.com</email>
    	<uri>http://www.example.com/JBloggs/</uri>
    </author>
    <content type="text/xml">
	    <SAMPBIND xmlns="http://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
	    	<data_field>
	    	 Here is content for my posted entry
		   </data_field>
	    </SAMPBIND >
    </content>
</entry>
This is the response that CICS sends:
HTTP/1.1 201 Created
Content-Type: application/atom+xml;type=entry
Content-Length: 1029

<?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 posted entry</title>
    <summary>
    This is my new posted 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 content for my posted entry
	    	</data_field>
    	</SAMPBIND >
    </content>
</entry>


dfhtl_atom_coll_servroutine_clientpost.html | Timestamp icon Last updated: Sunday, 4 June 2017