Building RESTful Interfaces

Steve Shaw

• What is REST?

• The precepts of a RESTful Interface

• Security

• Show how to implement a REST interface within the InterSystems Platform

We will Cover

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 state-machine), 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.”

"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

Or…

"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

Even Better…

• 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

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.

Principles of REST

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)

RESTful Web Service

CRUD operations

• REST operations fall under 4 types (CRUD) which are defined as http protocol methods:

REST HTTP

Create Post POSThttps://api.twitter.com/1.1/statuses/retweet/241259202004267009.json

Read Get GEThttps://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 requesthttp://www.igroup.com/order?ordernum=12345

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

URL / URI

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

conception

• Sophisticated security models can be difficult to implement

Security

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

Cache Implementation

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

Example: Hello World Redux

This service will provide access to a translation of “HELLO WORLD” into other languages.

Any Questions?

Q & A