Building RESTful
Interfaces
Steve Shaw
We will Cover
• What is REST?
• The precepts of a RESTful Interface
• Security
• Show how to implement a REST interface
within the InterSystems Platform
What is REST
• Architectural style for web Applications
introduced by Roy Fielding
• “Representational State Transfer is intended to evoke
an image of how a well-designed web application
behaves: a network of web pages (a virtual statemachine), where the user progresses through an
application by selecting links (state transitions),
resulting in the next page (representing the next state
of the application) being transferred to the user and
rendered for their use.”
Or…
"REST emphasizes scalability of component
interactions, generality of interfaces,
independent deployment of components, and
intermediary components to reduce interaction
latency, enforce security, and encapsulate legacy
systems. ”
- Webopedia
Even Better…
"Representational state transfer (REST) is a
distributed system framework that uses Web
protocols and technologies. The REST
architecture involves client and server
interactions built around the transfer of
resources. The Web is the largest REST
implementation
- Techopedia
REST
• Rest is not a standard or protocol, REST is an
architectural style.
• REST makes use of existing web standards
such as HTTP, URL, XML, JSON, etc..
• REST is resource oriented. Resources or
pieces of information, are addressed by URIs
and passed from server to client or vice versa
Principles of REST
• Uniform interface:
simplifies and decouples the
architecture, which enables each part to evolve independently.
• Stateless: no client context being stored on the server
between requests. Each request all of the information necessary to
service the request
• Cacheable: Well-managed caching partially or completely
eliminates some client–server interactions, further improving
scalability and performance.
RESTful Web Service
A RESTful web service is a web API implemented
using HTTP and the principles of REST.
• A collection of resources identified by a directory
structure-like URI
• E.g.:
https://www.googleapis.com/calendar/v3/calendars/joe.bloggs/events
• Operations based explicitly on HTTP methods (GET, POST, PUT,
DELETE)
• Information transfer based on Internet media types, commonly JSON.
Other types include XML,HTML, CSV (text)
CRUD operations
• REST operations fall under 4 types (CRUD) which are
defined as http protocol methods:
REST
HTTP
Create
Post
POST
https://api.twitter.com/1.1/statuses/retweet/241259202004267009.json
Read
Get
GET
https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=twitterapi
&count=2
Update
Put
PUT
https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
Delete
Delete
DELETE
https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
REST Advantages
• REST
•
•
•
•
Simplicity (easy to use, maintain and test)
Many options for representations(JSON, CSV, HTML, XML)
Human Readable Results
Performance
•
•
•
•
•
Scalable architecture
Lightweight requests and responses
Easier response parsing
Saves bandwidth(Caching, Conditional GET..)
Well suited clients using JSON representations
REST Advantages
• Soap request
<?xml version=“1.0”?>
<soap:Envelope xmlns:soap=http://www.w3.org/2001/12/soap-envelope
soap:encodingStyle=http://www.w3.org/2001/12/soap-encoding>
<soap:Body ord=“http://www.igroup.com/order”>
<ord:GetOrderDetails>
<ord:OrderNumber>12345</ord:OrderNumber>
</ord:GetOrderDetails>
</soap:Body>
</soap:Envelope>
• REST request
http://www.igroup.com/order?ordernum=12345
URL / URI
REST interfaces are defined via a URL/URI
• URI – Uniform Resource Identifier
• Identifies a specific Resource on the network
• Example: http://www.igroup.com/order
• URL – Uniform Resource Locator
• Provides access to a specific representation of a
resource on the network
• http://www.igroup.com/order?ordernum=12345 or
• http://www.igroup.com/order/ordernum/12345
Security
• Security is up to the Interface developer
• REST has no predefined methods for Security
• Security should take advantage of what is
already available for Web Applications
• SSL/TLS (https:)
• OpenId Authorization (Oauth)
• Hash-based Message Authentication Code (HMAC)
Security
• REST is exposed to all the same vulnerabilities
as an other Web based Applications
• Encrypt any sensitive payload or static keys
• Note HMAC does not encrypt data, a common missconception
• Sophisticated security models can be difficult
to implement
Cache Implementation
• New class in 2014.1 - %CSP.REST
• In SMP register the Dispatch Class which
matches your REST application base URL
• System>Security Management>Web Applications>Edit Web
Application
• New web application /csp/samples/globalsummit
• Dispatch Class: Rest.Broker
• Use the UrlMap Xdata block to route requests
to HTTP operation and target class method
• XData UrlMap {
<Routes>
<Route Url="/employee/html/list" Method="GET" Call="Rest.HTML:GetAllEmployees"/>
</Routes>}
Example: Hello World Redux
This service will provide access to a translation of
“HELLO WORLD” into other languages.
In this example we will:
• Configure the Web application
• Show the setup of a REST interface dispatch class
• Show the implementation options for the service
resources (methods)
• Show the results
Q&A
Any Questions?