Abstract
Replace the introduction of the APP with the one here.
Status
Withdrawn.
Rationale
The introduction to the APP attempts to cover all possible scenarios. As a result, it becomes incomprehensible and says little that isn't in RFC2616 and today's popular REST literature. Explicitly cutting down the introduction to cover Atom entries only will make the protocol much easier to understand for new implementors. Nouns like "Outline" can of course be swapped out by the editors to maintain consistency with the rest of the document. Alternatively, section 3.1 can be omitted if the WG elects to remove the introspection document from the spec.
Proposal
Replace Sections 4 and 5 as follows
3. The Atom Publishing Protocol Model
The APP uses HTTP to operate on collections of Web resources represented by Atom feeds [AtomFormat]. This section illustrates the editing cycle for Atom entries.
-
GET is used to retrieve a representation of a resource or perform a read-only query.
-
POST is used to create a new, dynamically-named resource.
-
PUT is used to update a known resource.
-
DELETE is used to remove a resource.
3.1 Discovery
To discover the location of the feeds exposed by an APP service, the client must locate and request an APP Outline. APP Outlines describe the layout of an APP service.
Client Server | | | 1.) GET Outline URI | |------------------------------->| | | | 2.) Service Outline Doc | |<-------------------------------| | |
-
The client sends a GET request to the Service Outline Resource.
-
The server responds with a APP Outline Document containing the locations of feeds provided by the service. The content of this document can vary based on aspects of the client request, including, but not limited to, authentication credentials.
3.2 Listing
Once the client has discovered the location of a feed, it can request a listing of the feed's entries. However, a feed might contain an extremely large number of entries, so servers are likely to list a small subset of them by default.
Client Server | | | 1.) GET to Atom Feed URI | |------------------------------->| | | | 2.) 200 OK, Atom Feed Doc | |<-------------------------------| | |
-
The client sends a GET request to the Atom Feed's URI.
-
The server responds with an Atom Feed Document containing a full or partial listing of the feed's membership.
3.3 Authoring
After locating a feed, a client can add entries by sending a POST request to the feed; other changes are accomplished by sending HTTP requests to each entry. 3.3.1 Create
Client Server | | | 1.) POST Entry to Feed URI | |------------------------------->| | | | 2.) 201 Created @ Location | |<-------------------------------| | |
-
The client sends an Atom Entry to the server via HTTP POST. The Request URI is that of the Atom Feed.
-
The server responds with a response of "201 Created" and a "Location" header containing the URI of the newly-created Atom Entry.
3.3.2 Read
Client Server | | | 1.) GET or HEAD to Entry URI | |------------------------------->| | | | 2.) 200 OK Atom Entry | |<-------------------------------| | |
-
The client sends a GET (or HEAD) request to the entry's URI.
-
The server responds with an Atom Entry document.
3.3.3 Update
Client Server | | | 1.) PUT to Entry URI | |------------------------------->| | | | 2.) 200 OK | |<-------------------------------| | |
-
The client PUTs an updated Atom Entry Document to the entry's URI.
-
The server responds with a successful status code.
3.3.4 Delete
Client Server | | | 1.) DELETE to Entry URI | |------------------------------->| | | | 2.) 204 No Content | |<-------------------------------| | |
-
The client sends a DELETE request to the entry's URI.
-
The server responds with a successful status code.
3.4 Success and Failure
HTTP defines classes of response. HTTP status codes of the form 2xx signal that a request was successful. HTTP status codes of the form 4xx or 5xx signal that an error has occurred, and the request has failed. Consult the HTTP specification for more detailed definitions of each status code.
