Controling instrument in the RESTful way

Tony Lam

Bragg Institute

Agenda

1. What is REST?

2. How instruments be controlled in the RESTful way?

Representational State Transfer (ReST)

is an Architectural Stylefor distributed hypermedia systems

- Roy Fielding’s doctoral dissertation (2000)

Architectural Style

Queen Victorian Building, SydneyGlasgow City Chambers, UK

Constraint 1: Client-Server

Constraints:1. Client-Server

Client Server

Rationale:• Separation of concern

Protocol connector

uniform interface(eg HTTP)

Constraint 2: Stateless

Constraints:1. Client-Server

2. Stateless

Client

Server

Rationale:• Separation of concern• Scalability

Client

Client

Protocol connector

Constraint 3: Cacheable

Constraints:1. Client-Server

2. Stateless

3. Cacheable

Rationale:• Separation of concern• Scalability• Efficiency

Client

Server

Client

Client

$

$

$

$ … with cache

Protocol connector

Constraint 4: Layered

Constraints:1. Client-Server

2. Stateless

3. Cacheable

4. Layered

Rationale:• Separation of concern• Scalability• Efficiency• Encapsulation of legacy services• Load balancing

Client

GatewayClient

Client

$

$

Firewall Legacy System

Server$ $

LegacyProtocol

$ … with cache

Protocol connector

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 hypermedia links to identify other resources

Examples

Database record of the user #1234http://example.com/users/1234

Last name of the user #1234http://example.com/users/1234/lastname

Today’s Sydney weatherhttp://example.com/sydney/weather/today orhttp://example.com/sydney/weather/2008/11/4

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

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

Examples

A circle with URI http://example.com/circle

GET /circle HTTP/1.1Host: example.com Accept: image/jepg

GET /circle HTTP/1.1Host: example.com Accept: text/XML

GET /circle HTTP/1.1Host: example.com Accept: application/x-javascript

<shape color=“blue”> <cartesian> x^2 + y^2 = 4 </cartesian></shape>

{centre:0, radius:2, colour:”blue”}

Examples in Scientific DomainDepending on your client application, you may read the temperature

controller history in the following forms:

Raw numbers for processingURI: http://instr.facility.org/sample_environments/tempController1/graph

Result: Comma separated value (CSV) of entire history

GUI Status DisplayURI: 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:

State Transfer

The word “Representational State Transfer” (REST) comes from how the state of resources (in various representations) flow within the client application.

ClientServer

a b c d e

1 2 3 4a a

ActualResources

State of resource(in different representations)

a

3

requesta

aresponse

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

HTTP Methods

HTTP method CRUD equivalent Safe Idempotent Object-Orientated API

GET Read Y Y resource.get()

PUT Update (create) N Y resource.put(request)

POST Create (update, delete) N N resource.post(request)

DELETE Delete N Y resource.delete()

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

<<interface>>Resource

GETPUTPOSTDELETE

/sample_environments

GET – list all sample environments (links)PUT – unusedPOST – register new a sample environmentDELETE – unused

/scanners/2theta_scanner

GET – get scan statusPUT – unusedPOST – run 2 theta scanDELETE – unused

/sample_environments/{id}

GET – get sample environment detailsPUT – unusedPOST – unusedDELETE – remove sample environment

/sample_environments/{id}/target

GET – get sample environment targetPUT – set sample environment targetPOST – unusedDELETE – unused

Assume those resources are available:

http://instr.facility.org/sample_environments/ sample environment listing resourcehttp://instr.facility.org/sample_environments/tempController1 <-- temp controller #1 resourcehttp://instr.facility.org/sample_environments/tempController1/target <-- temp controller #1 target resource

HTTP Report Status

• Successful Codes (2XX): 200 OK 201 Created 202 Accepted 204 No Content

• Redirection Codes (3XX): 301 Moved Permanently 304 Not Modified

• HTTP provides rich set of standardised return status code for error handling.

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

Traditional Instrument Control

InstrumentNetwork

TraditionalDesktop Client

(Java + Control System Adapter)

Device Server

drive(new_set_point)

read(current_value)

RESTful Instrument Control

REST Server

InstrumentNetwork

TraditionalDesktop Client

(Java + Apache HTTP client)

Device Server

POSTnew set point

$ drive(new_set_point)

read(current_value)

GETcurrent value

$ … with cache

Protocol connector

RESTful Instrument Control

REST Server

InstrumentNetwork

Browser

(Firefox + Poster plugin)

Rich Internet Application

(Adobe Flex + mx:HTTPService)

TraditionalDesktop Client

(Java + Apache HTTP client)

ScriptingApplication

(Python + httplib)

Device Server

$

$

Resource Management Tool

PUTnew device

DELETEexisting devicePOST

GET

GET

$ … with cache

Protocol connector

CLOUD

Instrument Control in Web 2.0 Style

RESTful CS Server

InstrumentNetwork

Client D

Client C

Client A

Client B

Device Server

$

$

Yahoo!REST Server

Amazon E2REST Server

Amazon S3REST Server

Data Storage

Computation Box

Web Service(news, map, weather)

FAQ

• Is REST just another RPC technology like XML-RPC or CORBA?

• Does REST support publish / subscribe pattern?

FAQ (cont.)

• Does my control system need to be refactored completely to adapt REST?

• Does REST work with HTTP only?

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

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