POST
This method of HTTP creates a new
object linked to and subordinate
to the specified object. The content
of the new object is enclosed as
the body of the request.
The POST method is desiged to allow
a uniform function to cover
- Annotation existing documents;
- Posting a message to a bulletin board
topic, newsgroup, mailing list, or
similar group of articles;
- Adding a file to a directory;
- Extending a document during authorship.
The client may not assume any postconditions
of the method in terms of web topology.
For example, if a POST is accepted,
the effect may be delayed or overruled
by human moderation, batch processing,
etc. The client should not be surprised
if a link is not immediately (or
never) created.
However, the semantics are a request
for a link to be made from the object
whose URL is quoted to the new, enclosed,
object.
If no URL for the NEW object is given
by the client, the server is requested
to see to the storage of the new
object. That is, the server does
not have to store it but will have
to return a URL be which it can later
be retrieved. The semantics of this
method (currently) imply nothing
of any undertakings by the server
to maintain the availability of the
object.
If the client gives a URL, then the
server is not obliged to store the
object, but may take a copy and may
in that case issue a new URL.
Return object headers
The method shall return a set (possibly
empty) of object headers for the
newly posted object. If a URL has
been assigned by the server, then
that may be included. Similarly,
if a URN has been assigned, then
that shall be returned. Other things
which may be returned include for
example the expiry-date if any. The
server may return the entire metadata
for the object (as in the HEAD command),
or a subset of it.
The object body shall not be returned,
so the transaction shall end with
the blank line terminating the headers.
Link type
The link type may be specified by
explicitly giving a (reverse) link
in the object header of the linked
object. If a link or links between
the two objects are present in those
headers, then that link is used.
If no such link is specified, then
the server should generate a link.
The link type in this case is determined
by the server. The server may perform
other operations as a result of the
new object being added: lists and
indexes might be updated, for example.
Submission
When articles are submitted, the
analogy of being addeed to a body
of knowledge by being linked is close.
When a form is submitted, this can
be done with POST, though in this
case side-effects will be expected.
(Should submission for action have
a different method -- see showmethod
-- or should it be just POST for
simplicity? When interfacing with
other systems such as bews and mail,
the distinction is not made as the
system does not have the ability
to distinguish different methods.
We now have a possibility of making
a separate action, though.)
The client has no way of knowing
what data formats the server is prepared
to accept. This may not be a serious
problem, but it may be if the server
has some restrictions. This applies
to all submissions of object content
from client to server, for all methods.
Related methods.
When a new URL has been returned
by the server, it may in general
(typically, but not necessarily)
be usable as the argument of DELETE
, GET , PUT , etc, methods.
To make a link between two existing
objects, see LINK.
Tim BL