Controling instrument in the RESTful way

1. Controling instrument in the RESTful way Tony Lam Bragg Institute

2. Agenda • What is REST? • How instruments be controlled in the RESTful way?

3. Representational State Transfer (ReST) is an Architectural Style for distributed hypermedia systems - Roy Fielding’s doctoral dissertation (2000)

4. Architectural Style Glasgow City Chambers, UK Queen Victorian Building, Sydney

5. Constraint 1: Client-Server Protocol connector Constraints: • Client-Server Client uniform interface (eg HTTP) Server • Rationale: • Separation of concern

6. Constraint 2: Stateless Protocol connector Constraints: • Client-Server • Stateless Client Server Client Client • Rationale: • Separation of concern • Scalability

7. Constraint 3: Cacheable Protocol connector … with cache $ Constraints: • Client-Server • Stateless • Cacheable Client $ Server Client $ Client $ • Rationale: • Separation of concern • Scalability • Efficiency

8. Constraint 4: Layered Protocol connector … with cache $ Constraints: • Client-Server • Stateless • Cacheable • Layered Client $ Gateway Firewall Server Legacy System Client $ $ Legacy Protocol Client $ • Rationale: • Separation of concern • Scalability • Efficiency • Encapsulation of legacy services • Load balancing

9. Concept 1: Resource • Any information that can be named is abstracted to “resource” • Examples: document, image, database record, application state and functionality, etc • Every resource is uniquely addressable • via Uniform Resource Identifier (URI) in HTTP • URIs are used as hypermedialinks to identify other resources

10. Examples Database record of the user #1234 • http://example.com/users/1234 Last name of the user #1234 • http://example.com/users/1234/lastname Today’s Sydney weather • http://example.com/sydney/weather/today or • http://example.com/sydney/weather/2008/11/4

11. Examples in Scientific Domain CONTROL: Temperature reading of temperature controller 1 • http://instr.facility.org/sample_environments/tempController1/temperature DATA STORAGE: The first dataset in the NeXus file nx0094 from the repository • http://instr.facility.org/repository/nx0094/nxroot/nxentry/1/nxdata/1/data COMPUTATION: Summation of 2 + 3 • http://instr.facility.org/calculator/sum/2/3

12. Concept 2: Representation • Resources are manipulated by exchanging their representations between components (client and server)‏ • Representation captures the state of a resource, or the actual information if the resource is a document • Each resource can have multiple representation • Representation has associated content type, eg HTML

13. Examples A circle with URI http://example.com/circle • GET /circle HTTP/1.1 • Host: example.com • Accept: text/XML • GET /circle HTTP/1.1 • Host: example.com • Accept: application/x-javascript • GET /circle HTTP/1.1 • Host: example.com • Accept: image/jepg • <shape color=“blue”> • <cartesian> • x^2 + y^2 = 4 • </cartesian> • </shape> • {centre:0, radius:2, colour:”blue”}

14. Examples in Scientific Domain Depending on your client application, you may read the temperature controller history in the following forms: Raw numbers for processing URI: http://instr.facility.org/sample_environments/tempController1/graph Result: Comma separated value (CSV) of entire history GUI Status Display URI: http://instr.facility.org/sample_environments/tempController1/graph/png Result: Filtered GUI Status Display (limited to show past 5 min) URI: http://instr.facility.org/sample_environments/tempController1/graph/png?past=5min Result:

15. State Transfer Client Server request • The word “Representational State Transfer” (REST) comes from how the state of resources (in various representations) flow within the client application. a a b c d e 3 1 2 3 4 a a a a response State of resource (in different representations) Actual Resources

16. Concepts 3: Uniform Interface • All resources use a set of standard operations for transferring state between client and resource. • Easy to use in every programming language

17. HTTP Methods Safe: no changes to any data on the server (no obligation) Idempotent: repeat without changing resource

18. /sample_environments GET – list all sample environments (links) PUT – unused POST – register new a sample environment DELETE – unused /sample_environments/{id} <<interface>> Resource GET – get sample environment details PUT – unused POST – unused DELETE – remove sample environment GET PUT POST DELETE /sample_environments/{id}/target GET – get sample environment target PUT – set sample environment target POST – unused DELETE – unused /scanners/2theta_scanner GET – get scan status PUT – unused POST – run 2 theta scan DELETE – unused Assume those resources are available: http://instr.facility.org/sample_environments/ sample environment listing resource http://instr.facility.org/sample_environments/tempController1 <-- temp controller #1 resource http://instr.facility.org/sample_environments/tempController1/target <-- temp controller #1 target resource

19. HTTP Report Status • HTTP provides rich set of standardised return status code for error handling. • Successful Codes (2XX): • 200 OK • 201 Created • 202 Accepted • 204 No Content • Redirection Codes (3XX): • 301 Moved Permanently • 304 Not Modified • Client Errors (4XX): • 400 Bad Request • 401 Unauthorized • 403 Forbidden • 404 Not Found • 405 Method Not Allowed • Server Errors (5XX): • 500 Internal Server Error • Security is supported in HTTP by authenticating via login name and password. • Testing can be done with just a web browser!

21. Traditional Instrument Control Traditional Desktop Client (Java + Control System Adapter) drive(new_set_point) read(current_value) Instrument Network Device Server

22. RESTful Instrument Control Protocol connector Traditional Desktop Client (Java + Apache HTTP client) … with cache $ POST new set point GET current value REST Server $ drive(new_set_point) Instrument Network Device Server read(current_value)

23. RESTful Instrument Control Protocol connector Traditional Desktop Client (Java + Apache HTTP client) … with cache $ Resource Management Tool DELETE existing device POST Scripting Application (Python + httplib) GET PUT new device REST Server $ Rich Internet Application (Adobe Flex + mx:HTTPService) Instrument Network Device Server GET Browser (Firefox + Poster plugin) $

24. Instrument Control in Web 2.0 Style Client A CLOUD Amazon S3 REST Server Data Storage Client B Computation Box Amazon E2 REST Server Client C Instrument Network RESTful CS Server Device Server $ Client D Yahoo! REST Server Web Service (news, map, weather) $

25. FAQ • Is REST just another RPC technology like XML-RPC or CORBA? • Does REST support publish / subscribe pattern?

26. FAQ (cont.) • Does my control system need to be refactored completely to adapt REST? • Does REST work with HTTP only?

27. References Internet • Representational State Transfer (Wikipedia) • http://en.wikipedia.org/wiki/Representational_State_Transfer • How I Explained REST to My Wife • http://tomayko.com/writings/rest-to-my-wife • InfoQ: A Brief Introduction to REST • http://www.infoq.com/articles/rest-introduction • Architectural Styles and the Design of Network-based Software Architectures (Roy Fielding's doctoral dissertation) • http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

28. References (cont.) Books • RESTful Web Services (O’Reilly, 2007) Presentations • ReSTful OSGi Web Applications Tutorial • http://www.eclipsecon.org/2008/sub/attachments/ReSTful_OSGi_Web_Applications_Tutorial.pdf • Real-time Web 2.0: Evolution of Middleware for Grid-based Instruments and Sensors • http://www.semanticgrid.org/OGF/ogf21/OGF21_McMullen3.ppt