This document discusses REST (Representational State Transfer) and RESTful APIs. It begins by explaining why REST is often misunderstood and discusses common misconceptions. It then covers the origins and constraints of REST as defined by Roy Fielding, including client-server, stateless, cache, uniform interface, layered system and code on demand. It also discusses the Richardson Maturity Model and concludes that REST is the best approach when considering long-term maintenance and evolution, despite having a higher start-up cost than other styles.

1. REST &
RESTful APIs
The State of Confusion

2. Why this topic?
 Not Well Understood
 ....consider how often we see software projects begin
with adoption of the latest fad in architectural design,
and only later discover whether or not the system
requirements call for such an architecture. Design-by-
buzzword is a common occurrence. At least some of
this behavior within the software industry is due to a
lack of understanding of why a given set of
architectural constraints is useful. (Roy Fielding 2000)
 Where to start when designing a RESTful API
 REST & Language/Client (C#, Javascript, Browser,
Devices)
 REST Encourages scalability
 REST Promotes Loose Coupling between Client &
Server

3. REST Beginnings
Architectural Styles and
the Design of Network-based Software
Architectures
by Roy Fielding (2000)
Ph.D. Dissertation
Introduction to the Representational State Transfer
(REST) architectural style for distributed
hypermedia systems, describing the software
engineering principles guiding REST and the
interaction constraints chosen to retain those
principles…..
Discusses Network-based Application Architectural
Styles with five additional styles discussed in
Chapter 3.

4. Why REST? | What is REST?
 REST attempts to minimize latency while
maximizing scalability.
 REST is a Style
 REST is a set of six constraints (one optional –
really 10)
 An API is NOT RESTful if it is not adhering to
these constraints which is not necessarily a bad
thing.
 While REST provides a number of benefits, it may
not be the right Architectural Style for a given
project
 What are the common misconceptions

5. Common Misconceptions
REST is NOT:
 URIs
 Identifying Resources
 Designing Responses (XML, JSON, XHTML,
HAL)
 HTTP Verbs (GET, PUT, POST, DELETE,….)
 Headers (Caching)
 HTTP Response Codes

6. REST Constraints
 Client-Server
 Stateless
 Cache
 Uniform Interface
 Layered System
 Code on Demand (only option constraint)

7. Client-Server
Separation of concerns is the principle behind the
client-server constraints. By separating the user
interface concerns from the data storage concerns,
we improve the portability of the user interface
across multiple platforms and improve scalability by
simplifying the server components. Perhaps most
significant to the Web, however, is that the
separation allows the components to evolve
independently, thus supporting the Internet-scale
requirement of multiple organizational domains.

8. Stateless
The client–server communication is further
constrained by no client context being stored on the
server between requests. Each request from any
client contains all of the information necessary to
service the request, and any session state is held in
the client.
This constraint induces the properties of visibility,
reliability, and scalability.
Like most architectural choices, the stateless
constraint reflects a design trade-off.

9. Cache
As on the World Wide Web, clients can cache
responses. Responses must therefore, implicitly or
explicitly, define themselves as cacheable, or not,
to prevent clients reusing stale or inappropriate
data in response to further requests. Well-managed
caching partially or completely eliminates some
client–server interactions, further improving
scalability and performance.
The advantage of adding cache constraints is that
they have the potential to partially or completely
eliminate some interactions, improving efficiency,
scalability, and user-perceived performance by
reducing the average latency.

10. Uniform Interface
The central feature that distinguishes the REST
architectural style from other network-based styles
is its emphasis on a uniform interface between
components.
Implementations are decoupled from the services
they provide, which encourages independent
evolvability.
REST is further defined by four interface
constraints: identification of resources;
manipulation of resources through representations;
self-descriptive messages; and, hypermedia as the
engine of application state.

11. Layered Systems
A client cannot ordinarily tell whether it is connected
directly to the end server, or to an intermediary
along the way. Intermediary servers may improve
system scalability by enabling load-balancing and
by providing shared caches. They may also enforce
security policies.
The primary disadvantage of layered systems is
that they add overhead and latency to the
processing of data.
Layers can be used to encapsulate legacy services
and to protect new services from legacy clients,
simplifying components by moving infrequently
used functionality to a shared intermediary

12. Code on demand (optional)
The final addition to our constraint set for REST
comes from the code-on-demand style.
REST allows client functionality to be extended by
downloading and executing code in the form of
applets or scripts.
This simplifies clients by reducing the number of
features required to be pre-implemented. Allowing
features to be downloaded after deployment
improves system extensibility.
An optional constraint allows us to design an
architecture that supports the desired behavior in
the general case, but with the understanding that it
may be disabled within some contexts.

13. REST Architectural Constraints
If a service violates any of the required constraints,
it cannot be considered RESTful.
Complying with these constraints, and thus
conforming to the REST architectural-style, enables
any kind of distributed hypermedia system to have
desirable emergent properties, such as
performance, scalability, simplicity, modifiability,
visibility, portability, and reliability.

14. REST Sub-Constraints
Identified as the "four interface constraints“ and are
only partially identified in the original text.
 Identification of Resources
 Manipulation of Resources through
Representations
 Self-Descriptive Messages
 Hypermedia as the Engine of Application State
(HATEOAS )
Much later (2008) Fielding published a blog to
further define the Hypermedia Constraint:
REST APIs must be hypertext driven
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven#comment-718

15. REST Sub-Constraints
Hypermedia as the Engine of Application State
A REST API should be entered with no prior knowledge beyond the
initial URI (bookmark) and set of standardized media types that
are appropriate for the intended audience (i.e., expected to be
understood by any client that might use the API). From that point
on, all application state transitions must be driven by client
selection of server-provided choices that are present in the
received representations or implied by the user’s manipulation of
those representations. The transitions may be determined (or
limited by) the client’s knowledge of media types and resource
communication mechanisms, both of which may be improved on-
the-fly (e.g., code-on-demand).

16. REST Architectural Elements
The Representational State Transfer (REST) style
is an abstraction of the architectural elements
within a distributed hypermedia system.
REST ignores the details of component
implementation and protocol syntax in order to
focus on:
- the roles of components,
- the constraints upon their interaction with other
components, - their interpretation of significant data
elements.
REST encompasses the fundamental constraints
upon components, connectors, and data that define
the basis of the Web architecture, and thus the
essence of its behavior as a network-based
application.

17. REST from a Different Angle
Richardson Maturity Model (RMM)
 Level 3
 Level 2 + Hypermedia
 RESTful Services
 Level 2
 Many URIs, many verbs
 CRUD services (e.g. Amazon S3)
 Level 1
 URI Tunneling
 Many URIs, Single verb
 Level 0
 SOAP, XML(POX), RPC
 Single URI

18. Conclusions
 RPC URI-Tunneling are the worst approach when comparing
benefits/effort ratio
 Start-up cost of HTTP-based Type I APIs is actually smaller than RPC
URI-Tunneling, mostly because the former leverages HTTP
mechanisms (methods, failure model, caching)
 Depending on the degree to which existing media types apply to the
problem domain HTTP-based Type II should be considered over HTTP-
based Type I because the start-up cost is almost identical.
If you are to any degree concerned with long term maintenance- and
evolution cost REST is the best solution despite the start-up cost.

19. References
 Architectural Styles and the Design of Network-based Software
Architectures
 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
 http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf
 Implementing Rest
 https://code.google.com/p/implementing-rest/
 Mike Amundsen Blog/Articles
 http://www.amundsen.com/blog/
 http://www.infoq.com/author/Mike-Amundsen
 Classification of HTTP-based APIs
 http://www.asp.net/web-api/overview
 ASP.NET Web API
 http://www.asp.net/web-api/overview
 Classification of HTTP-based APIs
 http://nordsc.com/ext/classification_of_http_based_apis.html
 Richardson Maturity Model
 http://martinfowler.com/articles/richardsonMaturityModel.html