REST and REST-fulness

REST and REST-fulness
David Waite
Ping Labs

!1

Copyright ©2012 Ping Identity Corporation. All rights reserved.

REST VS SOAP

!2


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


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

• 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


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)


Client/Server

Separation of user interface and
data storage concerns
•
•
•
•

!16

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


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

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


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 preimplemented
• 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
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

Example: Rails content type selection

class
UsersController
<
ApplicationController::Base

!

respond_to
:html,
:xml,
:json

!

def
index

respond_with(@users
=
User.all)

end

end

!31


Example: Rails Content Type Selection

GET
/users

#
HTML 
GET
/users 
Accepts:
application/json
#
JSON

 
GET
/users.xml

#
XML

!32


Bad Examples

GET
/user/changeGender?gender=f 
GET
/article/1/delete

!

POST
/soap 
SOAPAction:
urn:foo:SubmitTaxRecords

!33


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

Article

!

/articles/xyz

Comment

User

!

/articles/xyz/comments

Author

!

/users/dwaite

!35


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


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

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (10)

Similaire à REST and REST-fulness

Similaire à REST and REST-fulness (20)

Dernier

Dernier (20)

REST and REST-fulness