rest and rest-fulness
DESCRIPTION
Internal Lunch and Learn presentation on the legacy of XML and SOAP, what REST means, and what it takes to make a great RESTful APITRANSCRIPT
Copyright ©2012 Ping Identity Corporation. All rights reserved.
REST and REST-fulness
David Waite Ping Labs
!1
Copyright ©2012 Ping Identity Corporation. All rights reserved.
REST VS SOAP
!2
Copyright ©2012 Ping Identity Corporation. All rights reserved.
REST vs SOAP?
!3
• REST is a network data architecture for hypermedia systems
• SOAP is a XML-based message format • SOA is a software design and deployment
pattern !
• Often people say REST to imply a REST-influenced API design (RESTful API)
Copyright ©2012 Ping Identity Corporation. All rights reserved.
OK then, REST vs SOA
• REST and SOA are not mutually exclusive – REST abstracts network elements within a
distributed hypermedia system – SOA is the idea of having a decentralized
system by having components which supply services to other services
!4
Copyright ©2012 Ping Identity Corporation. All rights reserved.
The Mistakes of SOAP
• SOAP (Simple Object Access Protocol) was defined as a protocol abstraction on top of other protocol – HTTP, SMTP, JMS
• Ignores many lower-level protocol features • Reimplements them on top of its own
protocol • Uses XML for Object representation
!5
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML VS JSON
!6
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML vs JSON
• XML was designed as a reusable simplification of SGML in 1999 – Standard Generalized Markup Language
– XML could be said to be a language divided between two camps, people defining: – markup languages for documents
• HTML, SVG, MathML – interoperable data serialization
!7
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML vs JSON
• The initial influencers were almost purely document-oriented – tools would not manipulate XML as data but
be written to manipulate particular documents • XML has problems when representing
generic data • XML APIs are notoriously tedious for
extracting data
!8
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML vs JSON
• Short for JavaScript Object Notation • JSON was first used as a data format in
2001 by Douglas Crockford • First popular use was by Yahoo! in 2005,
Google in 2006 • Informational RFC describing the format
in 2006
!9
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML vs JSON
• JSON is based on a subset of the Javascript format used to define literal data structures – Floating point numerics – Booleans – Strings – Null – Arrays – Objects (Dictionaries/Maps)
!10
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML vs JSON
• Original popularity was because of AJAX Web sites like Gmail
• JSON format can be “eval”ed in JS – probably should regex to make sure there
isn’t any code – current browsers have a faster native JSON
parser built-in
!11
Copyright ©2012 Ping Identity Corporation. All rights reserved.
XML vs JSON
• Unlike XML, a native data format is defined • containing most of the primitives you need • But no native representation of:
– date/time – integers (vs double-precision floats) – binary streams – namespaced data
• No (finished) schema language
!12
Copyright ©2012 Ping Identity Corporation. All rights reserved.
WHAT IS REST?
!13
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Roy Fielding
!14
• A principal author of the HTTP specification
• Contributor to Apache HTTP Server
• Retconned “REST” as the motivation for the design of HTTP in his doctorate dissertation
Copyright ©2012 Ping Identity Corporation. All rights reserved.
What is REST
A set of six architectural constraints 1. Client/Server 2. Stateless 3. Cacheable 4. Layered System 5. Uniform Interface 6. Code on Demand (optional)
!15
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Client/Server
Separation of user interface and data storage concerns
• Portability of user interface • Scalability of server components • Independent deployment • Independent evolution
!16
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Stateless
Each request contains all needed information to understand the
request • session state is kept on the client • better recovery from failures • reduced server resource usage • scalability due to not needing manage state
between requests
!17
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Stateless Tradeoffs
• More traffic between client and server • May need to integrity or confidentiality-
protect data needed for future requests • Greater negative impact to bad client
implementation
!18
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Cacheable
• Responses are required to be interpreted as cacheable or non-cacheable
• Improves network efficiency • Improve server efficiency by avoiding
response generation • Improves client performance • But, stale data may decrease reliability
!19
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Layered System
• System can be composed of hierarchical layers
• Components can act as clients on one side and servers on the other
• Clients and Servers both do not need to know or do anything to support these components
• Reduces complexity of overall system • Intermediaries can affect performance
!20
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Code on Demand
• Client side can be extended by downloading code – javascript, applets, flash
• Reduces features which need to be pre-implemented
• But, affects visibility into what is happening • Security ramifications • Optional, may not be supported by some clients
!21
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Uniform Interface
• Generality to the client/server interface (HTTP, HTML)
• Reusability • Independent evolution • But, degrades efficiency
!22
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Interface Constraints
• Four additional interface constraints: !
1. Identification of Resources through URIs 2. Manipulation of Resources through
Representations 3. Self-Descriptive Messages 4. Hypermedia as the engine of application
state (HATEAOS)
!23
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Identification of Resources through URIs
• A request is meant to be targeted at a particular resource – via a Uniform Resource Identifier
• Independent from Representations of the resource returned or accepted – e.g., resource backed by database row
results in stylized HTML content • Provides generality and late binding
!24
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Self-Descriptive Messages
• A request or response can contain data and metadata
• Metadata is sufficient for processing data – Content-Type
• text/html • application/xml • application/personrecord+json
• Also, caching is part of a response
!25
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Manipulation of Resources through Representations
• A representation of the resource provides enough information to manipulate resource – Blog with comment form – List of records with delete buttons !
• URL of resource to client API?
!26
Copyright ©2012 Ping Identity Corporation. All rights reserved.
HATEAOS
Hypermedia as the engine of application state !
• Web is a non-linear medium formed by multimedia connected by hyperlinks
• Parties should not be assumed to understand structure of resources in order to be able to retrieve and manipulate them
!27
Copyright ©2012 Ping Identity Corporation. All rights reserved.
RESTFUL API DESIGN
!28
Copyright ©2012 Ping Identity Corporation. All rights reserved.
RESTful API Design fundamentals
• Understand HTTP as an underlying system – HTTP Methods – Content type selection – Cacheability – Safety and Idempotency of certain methods
!29
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Example: Rails RESTful Routes
!30
resources :photosVerb Path Action Used forGET /photos index display a list of all photos
GET /photos/new new return HTML form to create a new photo
POST /photos create create a new photoGET /photos/:id show display a specific photo
GET /photos/:id/edit edit return an HTML form for editing a photo
PATCH/PUT /photos/:id update update a specific photo
DELETE /photos/:id destroy delete a specific photo
creates seven different routes in your application, all mapping to the Photos controller:
resources :photos
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Example: Rails content type selection
!31
class UsersController < ApplicationController::Base ! respond_to :html, :xml, :json ! def index respond_with(@users = User.all) end end
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Example: Rails Content Type Selection
GET /users # HTML
GET /usersAccepts: application/json # JSON GET /users.xml # XML
!32
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Bad Examples
!33
GET /user/changeGender?gender=f
GET /article/1/delete !POST /soapSOAPAction: urn:foo:SubmitTaxRecords
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Cacheability
• As much of your API as possible should be designed with the idea of cacheability – Can I guarantee this data will be valid for a
certain period of time? – Is there a significant impact if the data goes
invalid before the time I specified? – How can I more easily check if data has
changed than generate a new response? • HEAD vs GET
!34
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Relations
/articles !/articles/xyz !/articles/xyz/comments !/users/dwaite
!35
Article
Author
Comment User
Copyright ©2012 Ping Identity Corporation. All rights reserved.
HATEAOS
• Don’t couple site design and resource locations to API design
• Lots of “Best Practice” and “Personal Preference” choices
!36
Copyright ©2012 Ping Identity Corporation. All rights reserved.
HATEAOS example
# Non-‐HATEAOS GET /users/dwaite # -‐> { “fn”: “Waite”, “gn”: “David”, groups: [“admin”, “labs”, “denver”] }
!37
Copyright ©2012 Ping Identity Corporation. All rights reserved.
HATEAOS example
# HATEAOS GET /users/dwaite # -‐> { “fn”: “Waite”, “gn”: “David”, groups: { “Administrator”: “/groups/admin”, “Ping Labs”: “/groups/pinglabs”, “Denver”: “/locations/Denver” }}
!38
Copyright ©2012 Ping Identity Corporation. All rights reserved.
Versioning
• Big design contention – Minor version updates through data - add to
response, do not change or remove – Major version update, indicate via
• new URL • new media type / mime type
– application/user+json;version=1 • some header
– Require version to be specified?
!39
Copyright ©2012 Ping Identity Corporation. All rights reserved.
More Information
• http://en.wikipedia.org/wiki/Representational_state_transfer
• http://www.stormpath.com/blog/designing-rest-json-apis
• http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
• http://groups.google.com/group/api-craft
!40
Copyright ©2012 Ping Identity Corporation. All rights reserved.
One More Thing: Cookies
• Cookies are generally non-RESTful – Against client/server and stateless
• client state on server • server state on client
– Against caching • Response containing cookies • Response generated from request cookies
• Try to use HTTP-level auth (like OAuth2)
!41