1. System Wide Information Management (SWIM)
REpresentational State Transfer (REST)–Based Service Oriented Architecture (SOA)

2. What is SOA?
SOA is an Information Technology (IT) architecture that defines systems as collections of interoperable, reusable services
SOA is a set of best practices for the organization and use of IT, and the discipline to follow them
In particular, an architecture oriented toward Services

3. Services: Lego-‘Ilities’
Interoperability
Unbreakability
Composability
Reusability
What the Business wants from IT!

4. Pros & Cons of Web Services (WS)
Relatively mature
Supported by most enterprise software
Transport protocol independent
Robust security & governance capabilities
Cons
Don’t guarantee interoperability
Loose coupling still a challenge
Verbose messages
Technical complexity

5. Definition of REST
REpresentational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web
Introduced and defined in 2000 by Roy Fielding in his doctoral dissertation
Fielding is one of the principal authors of the Hypertext Transfer Protocol (HTTP) specification

6. Architectural Styles
The WS family of standards and REST are architectural styles
Protocol-specific constraints on architecture
Neither requires or is necessary for SOA
SOA is itself an architectural style of Enterprise Architecture

7. REST Myths Myth: REST requires HTTP
Fact: It’s the verbs and links that matter, not the
transport protocol
But: The vast majority of REST is done with HTTP
Myth: You have to choose between REST and WS
Fact: Web Services Description Language (WSDL)
2.0 has a REST binding
But: WSDL 2.0 is not widely adopted
Myth: REST depends upon Secure Sockets Layer
(SSL) for security, which is often insufficient
Fact: Open Authorization (Oauth), eXtensible Access
Control Markup Language (XACML), even WS-
Security family can be used with REST
But: REST security is largely “roll your own”

8. Essential REST Terminology
Resource
An entity or capability on a network
Uniform Resource Identifier (URI)
String that identifies a resource over a network
Representation
Concrete manifestation of a resource
Hypermedia
A style of building systems for accessing information via a network of multimedia nodes connected by hyperlinks

9. What is a Resource?
Abstraction of an entity or capability you wish to expose
Anything you can give a URI to
Common resources:
Static Web pages
Dynamic Web pages
Documents
Images
Rich media (videos, etc.)
Method/procedure/operation calls WS

10. Uniform Interface
Clients interact with resources via a fixed set of verbs:
GET
Query the current state of the resource
Idempotent
Cacheable
POST
Create/initialize a resource
PUT
Update a resource
DELETE
Delete a resource

11. PUT vs. POST: Initializing a Resource
Wrong:
PUT /resource/{id}
Problem: ensuring id is unique
Right:
POST /resource
201 Created
Location: /resource/{id}

12. What is a URI?
A string of characters used to identify a name or a resource over a network (typically the Internet)
URIs are either Uniform Resource Locators (URLs) or Uniform Resource Names (URNs)
URL:
Identifies the resource
Specifies the means of acting upon or obtaining the representation
URN: urn:isbn:
Identifies resource by name in a particular namespace (identifier system)
Doesn’t specify location or how to access resource

13. RESTful vs. Remote Procedure Call (RPC)-based URIs
RPC-based URL:
Server-driven implementation
Lack of uniform interface introduces tight coupling
RESTful URL:
Client can try GET, POST, PUT, DELETE
Resource responds with appropriate self-describing representations

14. What is a Representation?
Data (and corresponding metadata) that provide a concrete manifestation of a resource
Resources typically have multiple representations
Often conform to standard Internet media types (formerly called MIME types)
Examples:
text/html
text/plain
application/xml
application/json
image/svg+xml

15. Content Negotiation
GET /resource
Accept: text/html, application/xml, application/json
The client lists the formats (Media types) that it understands
200 OK
Content-Type: application/json
The server chooses the most appropriate one for the reply

16. What is Hypermedia?
A style of building systems for organizing, structuring and accessing information via a network of multimedia nodes connected by hyperlinks
For example, the World Wide Web

17. Four Architectural Constraints
Separation of resource from representation
Manipulation of resources by representations
Self-descriptive messages
Hypermedia as the engine of application state
Without all four of these you’re not doing REST!

18. Separation of Resource from Representation
Resources are abstractions
The means for maintaining state of resources should be invisible to users of resource
Resource providers must hide limitations of underlying media/technology from users

19. Manipulation of Resources by Representations
A representation of a resource (including its metadata) can provide sufficient information to modify or delete the resource on the server
Provided client has permission
Such representations contain contract metadata for the resource

20. Self-Descriptive Messages
Each message includes enough information to describe how to process the message
For example, which parser to invoke may be specified by an Internet media type
Responses also explicitly indicate their cacheability

21. Hypermedia as the Engine of Application State
“HATEOAS”
Client interacts with application entirely through hypermedia
Representations reflect current state of app through hyperlinks
Hyperlinks contain opaque references to persistent state on the server
State does not necessarily mean data stored in representations

22. HATEOAS and URIs
Instead of having to learn all URIs a priori, the client can extract URIs from links at runtime
The server is free to change URIs or introduce new URIs on the same or some other server that provide a compatible behavior
Links that a server returns in representations can be contextual, by directing what the client can do subsequently
Links dynamically describe the contract between the client and the server in the form of a workflow at runtime

23. Contracted Services
Operations on resources are necessary but not sufficient to define Service contract
Each resource is responsible for returning contract metadata either for itself or for any resource it hyperlinks to
Example: Web form
…<form action=“/order” method=“POST”><input…
GET /formpage
POST /order
{data entered in form}

24. Contract Metadata for REST
Hyperlinks that create workflow at runtime
Contract metadata in representations that constrain further requests
Media types (standard and custom)
Namespaces

25. Essential REST-Based SOA Policies
All endpoints (clients, resources, topics) SHOULD follow common URI format
All requests and topics SHOULD be handled on the intermediary
Intermediaries SHOULD resolve all URIs into physical endpoints
Every resource SHOULD have a contracted representation (may have others as well)
Payloads MAY be loosely typed, MAY contain hyperlinks, MAY conform to custom media types

26. Differences Between WS-Based SOA & REST-Based SOA
Contracts
WS-Based SOA
REST-Based SOA
Documents external to participants
Links in representations + media types + namespaces + representation context
Fixed at design time
Governance-driven updates
Dynamic at run time

27. Differences Between WS-Based SOA & REST-Based SOA
Compositions
WS-Based SOA
REST-Based SOA
Composition logic defined at design time
Composition logic static or dynamic
Compositions executed by process engines
Compositions executed as hypermedia

28. Differences Between WS-Based SOA & REST-Based SOA
Handling State
WS-Based SOA
REST-Based SOA
Rely upon consumer
Rely upon hyperlinks
Rely upon underlying runtime
Rely upon custom message headers

29. Differences Between WS-Based SOA & REST-Based SOA
Operations
WS-Based SOA
REST-Based SOA
Specified in WSDL
GET, POST, PUT, DELETE
Inherit RPC-like characteristics that limit loose coupling
Avoid any RPC-like characteristics with proper URI formatting rules

30. Differences Between WS-Based SOA & REST-Based SOA
Data
Web Services-Based SOA
REST-Based SOA
Representations of various media types
Constrained by XML Schemas
Strongly or loosely typed
Strongly typed
Semantic information may be specified with custom media types
Semantic information largely manual

31. Questions and Comments?
?Ask participants: “Are there any questions about the material covered in this section?” 31

32. There are several ways to learn more about SWIM
The SWIM.gov website describes the SWIM program and provides news announcements for current issues
It also contains key documentation, including select briefings, the SWIM Newsletter and the SWIM Q&A 32