REST and REST-fulness
Upcoming SlideShare
Loading in...5
×
 

REST and REST-fulness

on

  • 654 views

Internal Lunch and Learn presentation on the legacy of XML and SOAP, what REST means, and what it takes to make a great RESTful API

Internal Lunch and Learn presentation on the legacy of XML and SOAP, what REST means, and what it takes to make a great RESTful API

Statistics

Views

Total Views
654
Views on SlideShare
654
Embed Views
0

Actions

Likes
1
Downloads
25
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

REST and REST-fulness REST and REST-fulness Presentation Transcript

  • 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? • 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 RESTinfluenced API design (RESTful API) !3 Copyright ©2012 Ping Identity Corporation. All rights reserved. View slide
  • 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. View slide
  • 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 • 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 !14 Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • What is REST A set of six architectural constraints 1. 2. 3. 4. 5. 6. !15 Client/Server Stateless Cacheable Layered System Uniform Interface Code on Demand (optional) Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • Client/Server Separation of user interface and data storage concerns • • • • !16 Portability of user interface Scalability of server components Independent deployment Independent evolution Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • Stateless Each request contains all needed information to understand the request • • • • !17 session state is kept on the client better recovery from failures reduced server resource usage scalability due to not needing manage state between requests Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • Stateless Tradeoffs • More traffic between client and server • May need to integrity or confidentialityprotect 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 preimplemented • 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 resources  :photos creates seven different routes in your application, all mapping to the Photos controller: resources  :photos Verb GET Path /photos Action Used for index display a list of all photos GET /photos/new new POST GET /photos /photos/:id create create a new photo show display a specific photo GET /photos/:id/edit edit PATCH/ /photos/:id PUT DELETE /photos/:id !30 return HTML form to create a new photo return an HTML form for editing a photo update update a specific photo destroy delete a specific photo Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • Example: Rails content type selection class  UsersController  <  ApplicationController::Base   !    respond_to  :html,  :xml,  :json   !    def  index          respond_with(@users  =  User.all)      end   end !31 Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • Example: Rails Content Type Selection GET  /users                                #  HTML
 GET  /users
 Accepts:  application/json  #  JSON   
 GET  /users.xml                        #  XML !32 Copyright ©2012 Ping Identity Corporation. All rights reserved.
  • Bad Examples GET  /user/changeGender?gender=f
 GET  /article/1/delete   ! POST  /soap
 SOAPAction:  urn:foo:SubmitTaxRecords !33 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   Article ! /articles/xyz   Comment User ! /articles/xyz/comments   Author ! /users/dwaite !35 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 Copyright ©2012 Ping Identity Corporation. All rights reserved.