rest and rest-fulness

Copyright ©2012 Ping Identity Corporation. All rights reserved.

REST and REST-fulness

David Waite Ping Labs

!1


REST VS SOAP

!2


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)


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


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


XML VS JSON

!6


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


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


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


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


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


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


WHAT IS REST?

!13


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


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


Client/Server

Separation of user interface and data storage concerns

• Portability of user interface • Scalability of server components • Independent deployment • Independent evolution

!16


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


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


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


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


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


Uniform Interface

• Generality to the client/server interface (HTTP, HTML)

• Reusability • Independent evolution • But, degrades efficiency

!22


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


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


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


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


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


RESTFUL API DESIGN

!28


RESTful API Design fundamentals

• Understand HTTP as an underlying system – HTTP Methods – Content type selection – Cacheability – Safety and Idempotency of certain methods

!29


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


Example: Rails content type selection

!31

class UsersController < ApplicationController::Base ! respond_to :html, :xml, :json ! def index respond_with(@users = User.all) end end


Example: Rails Content Type Selection

GET /users # HTML

GET /usersAccepts: application/json # JSON GET /users.xml # XML

!32


Bad Examples

!33

GET /user/changeGender?gender=f

GET /article/1/delete !POST /soapSOAPAction: urn:foo:SubmitTaxRecords


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


Relations

/articles !/articles/xyz !/articles/xyz/comments !/users/dwaite

!35

Article

Author

Comment User


HATEAOS

• Don’t couple site design and resource locations to API design

• Lots of “Best Practice” and “Personal Preference” choices

!36


HATEAOS example

# Non-‐HATEAOS GET /users/dwaite # -‐> { “fn”: “Waite”, “gn”: “David”, groups: [“admin”, “labs”, “denver”] }

!37


HATEAOS example

# HATEAOS GET /users/dwaite # -‐> { “fn”: “Waite”, “gn”: “David”, groups: { “Administrator”: “/groups/admin”, “Ping Labs”: “/groups/pinglabs”, “Denver”: “/locations/Denver” }}

!38


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


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

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


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

rest and rest-fulness

Technology