You are previewing Programming Amazon Web Services.

Programming Amazon Web Services

Cover of Programming Amazon Web Services by James Murty Published by O'Reilly Media, Inc.
  1. Programming Amazon Web Services
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    2. A Note Regarding Supplemental Files
    3. Preface
      1. What’s in This Book?
      2. Ruby and Interactive Examples
      3. Conventions Used in This Book
      4. Using Code Examples
      5. Safari® Enabled
      6. How to Contact Us
      7. Acknowledgments
    4. 1. Infrastructure in the Cloud
      1. Amazon Web Services for Infrastructure
      2. Thinking Like Amazon
      3. Reality Check
      4. Interfaces: REST and Query Versus SOAP
    5. 2. Interacting with Amazon Web Services
      1. REST-Based APIs
      2. User Authentication
      3. Performing AWS Requests
    6. 3. S3: Simple Storage Service
      1. S3 Overview
      2. Interacting with S3
      3. Buckets
      4. Objects
      5. Alternative Hostnames
      6. Access Control Lists
      7. Server Access Logging (Beta)
      8. Signed URIs
      9. Distributing Objects with BitTorrent
    7. 4. S3 Applications
      1. Share Large Files
      2. Online Backup with AWS::S3
      3. S3 Filesystem with ElasticDrive
      4. Mediated Access to S3 with JetS3t
    8. 5. EC2: Elastic Compute Cloud (Beta)
      1. EC2 Overview
      2. Interacting with EC2
      3. Keypairs
      4. Network Security by IP
      5. Finding Amazon Machine Images
      6. Controlling Instances
      7. Log In to an Instance
      8. Security Groups
      9. Managing and Sharing AMIs
      10. Console Output and Instance Reboot
    9. 6. Using EC2 Instances and Images
      1. EC2 Instances in Detail
      2. Data Management in EC2
      3. Modifying an AMI
      4. Registering an AMI
      5. Create an AMI from Scratch
    10. 7. EC2 Applications
      1. Dynamic DNS
      2. On-Demand VPN Server with OpenVPN
      3. Web Photo Album with Gallery 2
    11. 8. SQS: Simple Queue Service
      1. SQS Overview
      2. Interacting with SQS
      3. Queues
      4. Messages
      5. Queue Attributes
      6. Queue Access Control
    12. 9. SQS Applications
      1. Messaging Simulator
      2. Distributed Application Services with BOTO
      3. Automated Management of EC2 Instance Pools with Lifeguard
    13. 10. FPS: Flexible Payments Service (Beta)
      1. FPS Overview
      2. Interacting with FPS
      3. Managing Your Tokens
      4. Acquiring Third-Party Tokens
      5. Pay Now Widgets
    14. 11. FPS Transactions and Accounts
      1. Performing FPS Transactions
      2. Account Management and Information
    15. 12. FPS Advanced Topics
      1. Gatekeeper Language Guide
      2. Micropayments with FPS
      3. Building a Marketplace Application
      4. Subscribing to FPS Event Notifications
    16. 13. SimpleDB (Beta)
      1. SimpleDB Overview
      2. Interacting with SimpleDB
      3. Domains
      4. Items and Attributes
      5. Representing Data in SimpleDB
      6. Performing Queries
      7. Stock Price Database: A Mini SimpleDB Application
    17. A. AWS Resources
      1. AWS Online Resources
      2. Client Tools
      3. API Libraries
      4. Third-Party AWS Solutions
    18. B. AWS API Error Codes
      1. S3: Simple Storage Service
      2. EC2: Elastic Compute Cloud
      3. SQS: Simple Queue Service
      4. FPS: Flexible Payments Service
      5. SimpleDB
    19. Index
    20. About the Author
    21. Colophon
    22. SPECIAL OFFER: Upgrade this ebook with O’Reilly
O'Reilly logo

Interfaces: REST and Query Versus SOAP

AWS infrastructure services are made available through three separate APIs: REST, Query, and SOAP. In this book we will focus only on the REST and Query APIs and will not demonstrate how to use the SOAP APIs. We have a number of reasons for doing this, reasons which will become clearer after a brief explanation of the differences between the interfaces.

REST interfaces

The REST interfaces offered by AWS use only the standard components of HTTP request messages to represent the API action that is being performed. These components include:

  • HTTP method: describes the action the request will perform

  • Universal Resource Identifier (URI): path and query elements that indicate the resource on which the action will be performed

  • Request Headers: pieces of metadata that provide more information about the request itself or the requester

  • Request Body: the data on which the service will perform an action

Web services that use these components to describe operations are often termed RESTful services, a categorization for services that use the HTTP protocol as it was originally intended.

Query interfaces

The Query interfaces offered by AWS also use the standard components of the HTTP protocol to represent API actions; however these interfaces use them in a different way. Query requests rely on parameters, simple name and value pairs, to express both the action the service will perform and the data the action will be performed on. When you are using a Query interface, the HTTP envelope serves merely as a way of delivering these parameters to the service.

To perform an operation with a Query interface, you can express the parameters in the URI of a GET request, or in the body of a POST request. The method component of the HTTP request merely indicates where in the message the parameters are expressed, while the URI may or may not indicate a resource to act upon.

These characteristics mean that the Query interfaces cannot be considered properly RESTful because they do not use the HTTP message components to fully describe API operations. Instead, the Query interfaces can be considered REST-like, because although they do things differently, they still only use standard HTTP message components to perform operations.

SOAP interfaces

The SOAP interfaces offered by AWS use XML documents to express the action that will be performed and the data that will be acted upon. These SOAP XML documents are constructed as another layer on top of the underlying HTTP request, such that all the information about the operation is moved out of the HTTP message and encapsulated in the SOAP message instead.

For operations performed with a SOAP interface, the HTTP components of the request message are nearly irrelevant: all that is important is the XML document sent to the service as the body of the request. The valid structure and content of SOAP messages are defined in a Web Service Description Language (WSDL) document that describes the operations the service can perform, and the structure of the input and output data documents the service understands. To create a client program for a SOAP interface, you will typically use a third-party tool to interpret the WSDL document and generate the client stub code necessary to interact with the service.

The approach used in the SOAP interfaces are very different from those used by the REST and Query interfaces. Operations expressed in SOAP messages are completely divorced from the underlying HTTP message used to transmit the request, and the HTTP message components, such as method and URI, reveal nothing about the operation being performed.

The main reason we eschew the SOAP interface in this book is because we believe that SOAP interfaces in general add unnecessary complexity and overhead, effectively spoiling the simplicity and transparency that can make web services such powerful and flexible tools.[1] We are not alone in feeling this way. According to Amazon staff members, a vast majority of developers use the REST-based APIs to interact with AWS.

When a client performs an action using a REST-based interface, the messages are relatively simple. They can be constructed and interpreted by standard tools that recognize the HTTP protocol. SOAP messages, on the other hand, are much more complicated than those based on REST. To build a SOAP interface, you will generally require sophisticated tools to generate stub code before you can send any requests at all. Although such tools are readily available for some programming languages, typically those used in big business, they remain unavailable or immature on many platforms.

A secondary reason for avoiding SOAP is that we have tried to follow the KISS principle in this book. We have sought to keep our code samples as clear, simple, and broadly applicable as possible. Although most of our samples are written in the Ruby language, the techniques we demonstrate should be easy to apply in any other language that provides support for HTTP. If we presented SOAP interface clients, this code would demonstrate the subtleties of a particular third-party SOAP library much more effectively than it would the general-purpose techniques for using AWS that will work across multiple languages.


The steps for using a service’s REST or Query interface will be very similar for the SOAP interface as well. As the different interfaces all look similar and act in much the same way, readers already familiar with SOAP, and with access to high-quality tools for interacting with SOAP services, should be able to follow along with our API discussions using the SOAP interfaces. However, be aware that the SOAP service interfaces do not always provide all the functionality available in the REST or Query interfaces.

[1] The distinctions we allude to between different web service architectures are described in much more detail in RESTful Web Services by Leonard Richardson and Sam Ruby (O’Reilly). This book presents a strong case for avoiding the complexity that is SOAP, while discussing the theory and techniques necessary to build web services that take advantage of the simple, elegant, and efficient REST-based architecture that has served the Web so well.

The best content for your career. Discover unlimited learning on demand for around $1/day.