Making GET requests to Atom feeds or collections

A web client can obtain a list of the existing Atom entries in an Atom feed or collection by making an HTTP GET request to the URL of the collection, or obtain an individual Atom entry from the Atom feed or collection by making an HTTP GET request to the URL of the Atom entry.

Before you begin

If you want to edit a collection and 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. The URLs for Atom feeds are not available through Atom service documents, but are typically publicized in a relevant location, for example, as an invitation on a website to subscribe to a feed.

Procedure

To obtain a list of the existing Atom entries in the Atom feed or collection, make an HTTP GET request to the URL of the Atom feed or collection. Compose the request as follows:
1. Begin with a request line consisting of the GET method, followed by the path component of the URL of the Atom feed or 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.
  For an explanation of request lines, see HTTP requests.
2. If you want to obtain more or less than the default number of Atom entries that CICS sends for a single request for this Atom feed or collection, specify a query string at the end of the URL, with the name w (for "window") and the value as the number of Atom entries that you want to receive in this Atom document.
  This query string requests six Atom entries:
```
?w=6
```
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 feed or collection, if you did not already include the host name in the request line.
  - The Authorization header, with any security information required to access the Atom feed or collection, such as a user ID and password for basic authentication.
  Put an additional carriage return line feed (CRLF) after the last HTTP header to give an empty line.
Do not include a request body.
Send the request to the server.
The server returns an Atom feed document, which is a single HTTP response that contains a complete or partial list of the Atom entries in the Atom feed or collection.
Note: The elements in Atom documents served by CICS 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 the atom: prefix is not required for the child elements. However, in references to the elements in the CICS documentation, the atom: prefix is used in the element names for clarity.
If you received a partial list of the Atom entries in the Atom feed or collection, and you want to obtain more, make further HTTP GET requests to the links in the Atom feed document that specify further partial lists, as follows:
1. Use the URL stated in the <atom:link rel="next"> element to obtain the next window or partial list of entries.
  CICS provides this link for both Atom feeds and collections.
  
  As previously noted, CICS does not include the atom: namespace prefix for child elements, so the element appears in the Atom feed document as <link rel="next">.
2. Use the URL stated in the <atom:link rel="previous"> element to obtain the previous partial list of entries.
  CICS provides this link for collections.
3. Use the URL stated in the <atom:link rel="first"> element to obtain the first partial list of entries.
  CICS provides this link for collections.
4. Use the URL stated in the <atom:link rel="last"> element to obtain the last partial list of entries.
  CICS provides this link for collections.
  For Atom documents served by CICS, to improve performance, this partial list contains only the last Atom entry in the feed. You can use the <atom:link rel="previous"> links to retrieve all the previous partial lists.
Be aware that the links to further partial lists represent a snapshot of the Atom feed or collection at the point in time when CICS issues the Atom document containing them. When Atom entries are added to or deleted from the collection, the links might become invalid. The links are therefore only useful in the short term, to browse a collection that does not change quickly.
To obtain an individual Atom entry from the Atom feed or collection, make an HTTP GET request to the URL of the Atom entry, as stated in the <atom:link rel="self"> or <atom:link rel="edit"> element of the entry.
<atom:link rel="self"> provides the link for an Atom entry in a feed, and <atom:link rel="edit"> provides the link for an Atom entry in a collection. Atom entries in a collection might also have an <atom:link rel="self"> link.

Compose the request as follows:
1. Begin with a request line consisting of the GET 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.
  For an explanation of request lines, see HTTP requests.
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 Atom feed or collection, if you did not already include the host name in the request line.
  - The Authorization header, with any security information required to access the Atom feed or collection, such as a user ID and password for basic authentication.
  Put an additional carriage return line feed (CRLF) after the last HTTP header to give an empty line.
Do not include a request body.
Send the request to the server.
The server returns an HTTP response containing a copy of the individual Atom entry.

Example

This HTTP request is for an Atom collection with the URL http://www.example.com:80/web20/myfeed :

GET /web20/myfeed HTTP/1.1
Host: www.example.com:80

This HTTP request is for an Atom entry with the URL http://www.example.com:80/web20/entry/7:

GET /web20/entry/7 HTTP/1.1
Host: www.example.com:80

This example HTTP response shows an Atom document that CICS sends in response to the request for a single Atom entry. The example shows only the HTTP headers that are of interest for Atom feeds; further HTTP headers might be present in the response. The ETag header for the HTTP response gives the entity tag for the Atom entry, which you must use in the If-Match header if you make a PUT request to edit the entry.

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 1005
ETag: 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="https://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/7"/>
    <link rel="edit" href="http://www.example.com:80/web20/entry/7"/>
    <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:7</id>
    <title>This is entry 7</title>
    <summary>
    Entry 7 is about something to do with feeds...
    </summary>
    <category term="Test Feeds"/>
    <rights>Copyright (c) 2009, Joe Bloggs</rights>
    <published>2008-12-02T15:41:00</published>
    <author>
    	<name>Joe Bloggs</name>
    	<email>JBloggs@example.com</email>
    	<uri>http://www.example.com/JBloggs/</uri>
    </author>
    <contributor>
    	<name>John Doe</name>
    </contributor>
    <app:edited>2009-02-02T16:29:36+00:00</app:edited>
    <updated>2009-02-02T16:29:36+00:00</updated>
    <content type="text/xml">
	       <SAMPBIND xmlns="https://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
		      <data_field>
		      Here is some content for entry 7
		      </data_field>
	       </SAMPBIND >
    </content>
</entry>

This example HTTP response shows an Atom document that CICS sends in response to the request for a list of Atom entries from the Atom collection. Again, the example shows only the HTTP headers that are of interest for Atom feeds; further HTTP headers might be present in the response.

HTTP/1.1 200 OK
Content-Type: application/atom+xml
Content-Length: 8661

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
    <generator uri="https://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/myfeed"/>
    <link rel="edit" href="http://www.example.com:80/web20/myfeed"/>
    <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ</id>
    <title type="text">CICS ATOM FEED TITLE</title>
    <subtitle>CICS ATOM FEED SUBTITLE</subtitle>
    <rights>Copyright (c) 2009, Joe Bloggs</rights>
    <category term="my-first-feed"/>
    <author>
    	<name>Joe Bloggs</name>
    	<email>JBloggs@example.com</email>
    	<uri>http://www.example.com/JBloggs/</uri>
    </author>
    <contributor>
    	<name>John Doe</name>
    </contributor>
    <!--*****************************************************************-->
    <entry>
        <link rel="self" href="http://www.example.com:80/web20/entry/9"/>
        <link rel="edit" href="http://www.example.com:80/web20/entry/9"/>
        <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:9</id>
        <title>This is entry 9</title>
        <summary>
        Entry 9 is about something to do with feeds...
        </summary>
        <category term="Test Feeds"/>
        <rights>Copyright (c) 2009, Joe Bloggs</rights>
        <published>2008-12-02T15:41:00</published>
        <author>
        	<name>Joe Bloggs</name>
        	<email>JBloggs@example.com</email>
        	<uri>http://www.example.com/JBloggs/</uri>
        </author>
        <contributor>
        	<name>John Doe</name>
        </contributor>
        <app:edited>2009-02-02T16:29:36+00:00</app:edited>
        <updated>2009-02-02T16:29:36+00:00</updated>
        <content type="text/xml">
	        <SAMPBIND xmlns="https://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
		       <data_field>
		       Here is some content for entry 9
		       </data_field>
	        </SAMPBIND >
        </content>
    </entry>
    <!--*****************************************************************-->
    <entry>
        <link rel="self" href="http://www.example.com:80/web20/entry/8"/>
        <link rel="edit" href="http://www.example.com:80/web20/entry/8"/>
        <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:8</id>
        <title>This is entry 8</title>
        <summary>
        Entry 8 is about something to do with feeds...
        </summary>
        <category term="Test Feeds"/>
        <rights>Copyright (c) 2009, Joe Bloggs</rights>
        <published>2008-12-02T15:41:00</published>
        <author>
        	<name>Joe Bloggs</name>
        	<email>JBloggs@example.com</email>
        	<uri>http://www.example.com/JBloggs/</uri>
        </author>
        <contributor>
        	<name>John Doe</name>
        </contributor>
        <app:edited>2009-02-02T16:29:36+00:00</app:edited>
        <updated>2009-02-02T16:29:36+00:00</updated>
        <content type="text/xml">
	        <SAMPBIND xmlns="https://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
		       <data_field>
		       Here is some content for entry 8
		       </data_field>
	        </SAMPBIND >
        </content>
    </entry>
    <!--*****************************************************************-->
    <entry>
        <link rel="self" href="http://www.example.com:80/web20/entry/7"/>
        <link rel="edit" href="http://www.example.com:80/web20/entry/7"/>
        <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:7</id>
        <title>This is entry 7</title>
        <summary>
        Entry 7 is about something to do with feeds...
        </summary>
        <category term="Test Feeds"/>
        <rights>Copyright (c) 2009, Joe Bloggs</rights>
        <published>2008-12-02T15:41:00</published>
        <author>
        	<name>Joe Bloggs</name>
        	<email>JBloggs@example.com</email>
        	<uri>http://www.example.com/JBloggs/</uri>
        </author>
        <contributor>
        	<name>John Doe</name>
        </contributor>
        <app:edited>2009-02-02T16:29:36+00:00</app:edited>
        <updated>2009-02-02T16:29:36+00:00</updated>
        <content type="text/xml">
	        <SAMPBIND xmlns="https://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
		       <data_field>
		       Here is some content for entry 7
		       </data_field>
	        </SAMPBIND >
        </content>
    </entry>
    <!--*****************************************************************-->
    <entry>
        <link rel="self" href="http://www.example.com:80/web20/entry/6"/>
        <link rel="edit" href="http://www.example.com:80/web20/entry/6"/>
        <id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:6</id>
        <title>This is entry 6</title>
        <summary>
        Entry 6 is about something to do with feeds...
        </summary>
        <category term="Test Feeds"/>
        <rights>Copyright (c) 2009, Joe Bloggs</rights>
        <published>2008-12-02T15:41:00</published>
        <author>
        	<name>Joe Bloggs</name>
        	<email>JBloggs@example.com</email>
        	<uri>http://www.example.com/JBloggs/</uri>
        </author>
        <contributor>
        	<name>John Doe</name>
        </contributor>
        <app:edited>2009-02-02T16:29:36+00:00</app:edited>
        <updated>2009-02-02T16:29:36+00:00</updated>
        <content type="text/xml">
	        <SAMPBIND xmlns="https://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
		       <data_field>
		       Here is some content for entry 6
		       </data_field>
	        </SAMPBIND >
        </content>
    </entry>
</feed>