[Pki-devel] POST-a vs. POST-b

[Ade Lee]

I was asked today what the difference in the interface doc was between
POST-a and POST-b.  

Below is an excerpt from Restful Web Services (in the best practices
chapter) that explains in more detail.

Basically, POST-a is using POST to add a new resource.  You must use
POST instead of PUT if the server is responsible for the final URI.
Example, in creating a new request, the server is responsible for
assigning a request_id and hence the link to the uri -- /pki/request/$id
This is a good use of POST (as described in section 8.6.2)

8.6.3 describes the overloaded use of POST - which is as the result of a
submission of a form.  This is what I call POST-b - and what some call
POST-p (for POST-processor).  

We have tried to reduce the number of cases where POST-b is used.  Its
not bad in and of itself, but it makes the interface less clear and less
resource oriented or RESTful.  Sometimes we have to use it -- as Jack
specified for OCSP for instance.  In the case of CRLs, at this point I
just do not understand how that interface is supposed to work (and am
waiting for Andrew or Christina to tell me).

Hope this helps,
Ade

*********************************************
8.6.2. New Resources: PUT Versus POST

You can expose the creation of new resources through PUT, POST, or both.
But a client can only use PUT to create resources when it can calculate
the final URI of the new resource. In Amazon’s S3 service, the URI path
to a bucket is /{bucket-name}. Since the client chooses the bucket name,
a client can create a bucket by constructing the corresponding URI and
sending a PUT request to it.

On the other hand, the URI to a resource in a typical Rails web service
looks like /{database-table-name}/{database-ID}. The name of the
database table is known in advance, but the ID of the new resource won’t
be known until the corresponding record is saved to the database. To
create a resource, the client must POST to a “factory” resource, located
at /{database-table-name}. The server chooses a URI for the new
resource.
8.6.3. Overloading POST

POST isn’t just for creating new resources and appending to
representations. You can also use it to turn a resource into a tiny
RPC-style message processor. A resource that receives an overloaded POST
request can scan the incoming representation for additional method
information, and carry out any task whatsoever. This gives the resource
a wider vocabulary than one that supports only the uniform interface.

This is how most web applications work. XML-RPC and SOAP/WSDL web
services also run over overloaded POST. I strongly discourage the use of
overloaded POST, because it ruins the uniform interface. If you’re
tempted to expose complex objects or processes through overloaded POST,
try giving the objects or processes their own URIs, and exposing them as
resources. I show several examples of this in Section 8.8” later in this
chapter.

There are two noncontroversial uses for overloaded POST. The first is to
simulate HTTP’s uniform interface for clients like web browsers that
don’t support PUT or DELETE. The second is to work around limits on the
maximum length of a URI. The HTTP standard specifies no limit on how
long a URI can get, but many clients and servers impose their own
limits: Apache won’t respond to requests for URIs longer than 8 KB. If a
client can’t make a GET request to
http://www.example.com/numbers/1111111 because of URI length
restrictions (imagine a million more ones there if you like), it can
make a POST request to http://www.example.com/numbers?_method=GET and
put “1111111” in the entity-body.

If you want to do without PUT and DELETE altogether, it’s entirely
RESTful to expose safe operations on resources through GET, and all
other operations through overloaded POST. Doing this violates my
Resource-Oriented Architecture, but it conforms to the less restrictive
rules of REST. REST says you should use a uniform interface, but it
doesn’t say which one.

If the uniform interface really doesn’t work for you, or it’s not worth
the effort to make it work, then go ahead and overload POST, but don’t
lose the resource-oriented design. Every URI you expose should still be
a resource: something a client might want to link to. A lot of web
applications create new URIs for operations exposed through overloaded
POST. You get URIs like /weblog/myweblog/rebuild-index. It doesn’t make
sense to link to that URI. Instead of putting method information in the
URI, expose overloaded POST on your existing resources
(/weblog/myweblog) and ask for method information in the incoming
representation (method=rebuild-index). This way, /weblog/myweblog still
acts like a resource, albeit one that doesn’t totally conform to the
uniform interface. It responds to GET, PUT, DELETE... and also
“rebuild-index” through overloaded POST. It’s still an object in the
object-oriented sense.

A rule of thumb: if you’re using overloaded POST, and you never expose
GET and POST on the same URI, you’re probably not exposing resources at
all. You’ve probably got an RPC-style service.