confused about REST API / Query API

[Jan-Philip Gehrcke]

Hey there,

maybe this is a bit off-topic, but I would like to clarify the terms
REST API/Query API with your help. And since boto implemented both of
them, I hope it's not totally wrong.

Regarding S3, Amazon names the REST API/SOAP API as options. At EC2
one can choose between SOAP API/Query API. Can EC2's Query API be
called REST API, too?

I'm not sure about the terms. Wikipedia says (among others): REST
describes "any simple interface that transmits domain-specific data
over HTTP, without an additional messaging layer such as SOAP".

At S3 the REST API requests use HTTP body data, while the EC2 Query
API requests only use the "request line" (or URL). In both cases the
responses contain XML data. So.. I think there is an additional
messaging layer in both cases and I am confused!

Can you help me out there? How would you describe these EC2/S3 REST/
Query API's to a computer scientist? :-)

Thank you,

Jan-Philip Gehrcke

[Neil Soman]

Hello,

I can try to take a stab at it.

REST deals with resources. In case of the S3 API, resources are the
service, buckets and objects. It doesn't matter if the format is JSON,
HTML or XML. There are resources represented by URIs and operations on
the URI representation of the resource are used to manipulate the
resource. That is REST.

Amazon's EC2 Query API does not represent a resource as a URI.
Operations are encoded as URIs but the user is not manipulating a URI
that corresponds to a resource. For instance, if you want to create a
security group, you encode an operation "CreateSecurityGroup" in the
URI, but you are not really manipulating a URI that represents a
resource, i.e. the security group in this case.

See Chapter 5 of Fielding's thesis where it was first defined I think.

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Hope that helps.
neil

[Mitchell Garnaat]

I think that's a good explanation.  I would add one thing.  The AWS Query interfaces use only the GET verb and the actual action being performed is passed as a parameter in the request.  Also, they always return a 200 OK.  A real REST interface (like the S3 interface or the original but no longer available SQS interface) use a rich set of HTTP verbs (GET, PUT, DELETE, POST, HEAD) and leverage the HTTP response codes defined in the spec.

The AWS Query interface is really like SOAP messages transported via HTTP GET requests.  At least that's how I think of it.

Mitch

[Jan-Philip Gehrcke]

Thank you Neil and Mitch, you helped me a lot!

On 14 Jun., 19:17, Mitchell Garnaat <mitch.garn...@gmail.com> wrote:
> I think that's a good explanation.  I would add one thing.  The AWS Query
> interfaces use only the GET verb and the actual action being performed is
> passed as a parameter in the request.  Also, they always return a 200 OK.  A
> real REST interface (like the S3 interface or the original but no longer
> available SQS interface) use a rich set of HTTP verbs (GET, PUT, DELETE,
> POST, HEAD) and leverage the HTTP response codes defined in the spec.
>
> The AWS Query interface is really like SOAP messages transported via HTTP
> GET requests.  At least that's how I think of it.
>
> Mitch
>

> On Sun, Jun 14, 2009 at 12:13 PM, Neil Soman <neilso...@gmail.com> wrote:
>
> > Hello,
>
> > I can try to take a stab at it.
>
> > REST deals with resources. In case of the S3 API, resources are the
> > service, buckets and objects. It doesn't matter if the format is JSON,
> > HTML or XML. There are resources represented by URIs and operations on
> > the URI representation of the resource are used to manipulate the
> > resource. That is REST.
>
> > Amazon's EC2 Query API does not represent a resource as a URI.
> > Operations are encoded as URIs but the user is not manipulating a URI
> > that corresponds to a resource. For instance, if you want to create a
> > security group, you encode an operation "CreateSecurityGroup" in the
> > URI, but you are not really manipulating a URI that represents a
> > resource, i.e. the security group in this case.
>
> > See Chapter 5 of Fielding's thesis where it was first defined I think.
>

> >http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm<http://www.ics.uci.edu/%7Efielding/pubs/dissertation/top.htm>

[Jan-Philip Gehrcke]

I looked in a book to read about this topic again and found a really
nice summary explaining differences between REST and Query API and
stating a reason why SOAP API is not that famous on client side. If
you like to read this part, too, see below.

Furthermore, I concerned myself with the different API terms and
realizations within AWS. It turns out that the names for the APIs are
not always chosen consequently.

You can read about both, the book excerpt and the inconsistency, in
this blog post:
http://gehrcke.de/2009/06/aws-about-api/

Jan-Philip