confused about REST API / Query API

767 views
Skip to first unread message

Jan-Philip Gehrcke

unread,
Jun 14, 2009, 10:53:25 AM6/14/09
to boto-users
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

unread,
Jun 14, 2009, 12:13:49 PM6/14/09
to boto-...@googlegroups.com
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

unread,
Jun 14, 2009, 1:17:26 PM6/14/09
to boto-...@googlegroups.com
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

unread,
Jun 14, 2009, 7:55:29 PM6/14/09
to boto-users
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

unread,
Jun 29, 2009, 8:26:01 AM6/29/09
to boto-users
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
Reply all
Reply to author
Forward
0 new messages