Administering Atom feeds and Atom collections

A client can view the Atom entries in an Atom feed; Atom entries in an Atom feed are read-only and cannot be edited. A client can view, edit, create, or delete Atom entries in an Atom collection.

To discover which Atom feeds or collections are available on a server, the client requests a service document from the server. The service document lists the URLs of the Atom feeds and collections that are available to the client. The client can then interact with the Atom entries by sending HTTP requests to the server as follows:

GET: Retrieve a single Atom entry or a list of Atom entries. GET requests for a list of Atom entries are sent to the URL of the collection, as stated in the Atom service document. GET requests for a single Atom entry are sent to the URL of an individual Atom entry in the collection, as stated in the <atom:link rel="edit"> link for the entry.
POST: Create a new Atom entry. POST requests are sent to the URL of the collection.
PUT: Edit an existing Atom entry that the client has obtained using a GET request. PUT requests are sent to the URL of an individual Atom entry in the collection.
DELETE: Delete an existing Atom entry. DELETE requests are sent to the URL of an individual Atom entry in the collection.

For POST and PUT requests, the client sends a request body containing a complete Atom entry document. (CICS® does not support other media types in Atom collections.) Although a PUT request typically updates only a part of an existing entry, the client should send the whole entry, including the elements of the existing entry that were not edited, to avoid any possible misinterpretation by the server. The server adds the new entry or updates the existing entry, then sends an HTTP response to the client with an appropriate HTTP status code. The server can change, add to, or remove the items of metadata (such as the Atom ID or the date and time stamps) that the client provides for an entry. So when a client makes a successful POST or PUT request, the server also returns a copy of the new entry as the body of the response. CICS requires entity tags (ETags) for PUT requests for Atom entries in a collection, which enable the server to confirm that the client has based its editing requests on an up-to-date copy of the Atom entry.

RFC 5023 The Atom Publishing Protocol has a full statement of the protocol for interacting with Atom entries in a collection, and some examples of the HTTP requests and responses used.

For a collection for which CICS extracts data directly from a file or temporary storage queue without the involvement of a service routine, CICS carries out the actions of a server to process the client request, update the resource, and return a response to the client. Be aware that these actions modify the contents of the file or temporary storage queue permanently. CICS adds or edits records in response to POST and PUT requests. For DELETE requests relating to a file, CICS deletes the records, except in an ESDS where records cannot be deleted. For DELETE requests relating to a temporary storage queue, CICS removes the records by setting the first byte to 'FF'x. If these actions are not appropriate for your environment, use a service routine instead to handle the client requests.

CICS does not support some of the possible actions described for collections in the Atom Publishing Protocol (RFC 5023), in particular the following:

CICS does not support media resources and media link entries in collections. Media resources are specified by the Atom Publishing Protocol (RFC 5023) primarily as a means of organizing nontext content in a collection. When a client attempts to create an entry in a collection, CICS rejects with a 415 status code any client request that is not an Atom entry (with the media type application/atom+xml, with or without the type=entry parameter). Do not specify any additional media types in <app:accept> elements in a service document for CICS.
CICS does not reject Atom entries for a collection on the basis of categories. You can use the <app:categories> element in a service document or category document to specify acceptable categories for entries in a collection, but CICS does not police whether clients adhere to these categories.
For reasons of performance, CICS does not automatically return Atom entries in a collection in the order in which they were most recently edited (as shown by the <app:edited> element in the entry). This function is a SHOULD requirement in RFC 5023 for a full list of entries, but a MUST requirement for a partial list of entries. CICS deviates from this requirement in order to maintain acceptable response times while still providing the useful function of partial lists. If you are using a service routine to supply the entries to CICS, you can make the collection compliant by supplying the entries in the order in which they were last edited, if your resource is able to store this information.

Atom features not supported by CICS lists other unsupported items that are minor or do not relate specifically to collections.

For a collection served by CICS involving data that a service routine extracts from a resource and supplies to CICS, CICS passes the client request to the service routine in a set of containers. You must code your service routine to apply the request to the data in the resource and then return a response to CICS to send to the client. In this situation, you share the responsibility with CICS in some respects for compliance with the Atom Publishing Protocol (RFC 5023). Handling Atom collection editing requests in your service routine explains how your service routine can handle GET, POST, PUT, and DELETE requests for collections.

When you have finished setting up your Atom collection and (if necessary) your service routine, you can edit the entries using any suitable client that handles the HTTP protocol. The exact process for making the requests and viewing the responses varies depending on the client that you have chosen. For more information about how to interact with the entries in a collection using GET, POST, PUT, and DELETE requests, see Editing Atom collections using a web client.