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 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.”

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 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 REST 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 miss- conception 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?