RESTful Service
Discussions
Shawn Hu
OpenSG Service Definition, Feb 2010
Design Artifact Considerations
• XML schemas for message payload definition
• WSDL 2.0 for service definition in REST style
– Operation style & pattern
• style="http://www.w3.org/ns/wsdl/style/iri"
pattern="http://www.w3.org/ns/wsdl/in-out"
– Binding type:
• type="http://www.w3.org/ns/wsdl/http"
– Operation method (http verbs)
• whttp:method="GET" (or others)
OpenSG Service Definition, Feb 2010
Consumption XML Schema
• Consumption.xsd
OpenSG Service Definition, Feb 2010
RESTful Service Definition
• Input
– Using HTTP GET or POST following URL
naming convention
• Output
– Using XSD for return
OpenSG Service Definition, Feb 2010
Xpath for URI Design
http://www.openade.org/datastore/Consumption/MeterReading/IntervalBlocks/IntervalReadings/value
OpenSG Service Definition, Feb 2010
URI Naming Convention
• URI = <Base Resource Address>+<Resource
Path>+<Request>
– <Base Resource Address> - A base address where a web
service is located such as http://www.openade.org/datastore/
(not real address but for example only)
– <Resource Path> - A path to access resource component. This
path follows XSD Xpath convention such as
/Consumption/MeterReading/IntervalBlocks/IntervalReadings/ to
access interval readings as consumption
– <Request> - An optional field for arguments such as
?timeStamp=2010-02-02T00:00:00Z
– Example URI for a resource:
http://www.openade.org/datastore/Consumption/MeterReading/I
ntervalBlocks/IntervalReadings?timeStamp=2010-0202T00:00:00Z
OpenSG Service Definition, Feb 2010
Service Table
OpenSG Service Definition, Feb 2010
GET URI & Return XML
• Entry URI:
http://www.OpenSG.org/datastore/Consumption/MeterReading/IntervalBlock
s/IntervalReadings/value?timeStamp=2009-12-17T09:30:47Z
Note: <Resource Path> may need to truncated to only list <Immediate
Parent><Child> such as
http://www.OpenSG.org/datastore/IntervalReadings/value?timeStamp=200912-17T09:30:47Z
• Return XML:
<?xml version="1.0" encoding="UTF-8"?>
<m:Consumption>
<m:MeterReading>
<m:IntervalBlocks>
<m:IntervalReadings>
<m:timeStamp>2009-12-17T09:30:47Z</m:timeStamp>
<m:value>12.35</m:value>
</m:IntervalReadings>
</m:IntervalBlocks>
</m:MeterReading>
</m:Consumption>
OpenSG Service Definition, Feb 2010
POST Entry URI & XML
• Entry URI:
http://www.OpenSG.org/datastore/Consumption/MeterReading/IntervalBlock
s/IntervalReadings/value
• Resulting XML to post:
<?xml version="1.0" encoding="UTF-8"?>
<m:Consumption>
<m:MeterReading>
<m:CustomerAgreement>
<m:mRID>12345</m:mRID>
</m:CustomerAgreement>
<m:IntervalBlocks>
<m:IntervalReadings>
<m:timeStamp>2009-12-17T09:30:47Z</m:timeStamp>
<m:value>12.35</m:value>
</m:IntervalReadings>
</m:IntervalBlocks>
</m:MeterReading>
</m:Consumption>
OpenSG Service Definition, Feb 2010
Compressed/Truncated XML
• XML can be compressed or truncated as
below if space is limited using the POST
XML as an example:
<C><MR><CA><ID>12345</ID></CA><IB><IR><tS>2009-1217T09:30:47Z</tS><v>12.35</v></IR></IB></MR></C>
OpenSG Service Definition, Feb 2010
WSDL Design
– Operation Style & Pattern
• style=http://www.w3.org/ns/wsdl/style/iri
(W3C WSDL2.0)
– The content model of this element is defined using a complex type that
contains a sequence from XML Schema.
– The sequence MUST only contain elements.† It MUST NOT contain
other structures such as xs:choice. There are no occurrence
constraints on the sequence.
– The sequence MUST contain only local element children.† Note these
child elements can contain the nillable attribute.
– The localPart of the element's QName MUST be the same as the
Interface Operation component's {name}.†
– The complex type that defines the body of the element or its children
elements MUST NOT contain any attributes.†
– The children elements of the sequence MUST derive from
xs:simpleType, and MUST NOT be of the type or derive from
xs:QName, xs:NOTATION, xs:hexBinary or xs:base64Binary.†
Note: IRIs – Internationalized Resource Identifiers (IETF)
OpenSG Service Definition, Feb 2010
WSDL Design
– Operation Style & Pattern
• pattern=http://www.w3.org/ns/wsdl/in-out
(W3C WSDL2.0)
– The in-out message exchange pattern consists of exactly two
messages, in order, as follows:†
– A message:
» indicated by a Interface Message Reference component whose
{message label} is "In" and {direction} is "in"
» received from some node N
– A message:
» indicated by a Interface Message Reference component whose
{message label} is "Out" and {direction} is "out"
» sent to node N
– The in-out message exchange pattern uses the rule 2.2.1 Fault
Replaces Message propagation rule.†
– An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/ns/wsdl/in-out".
OpenSG Service Definition, Feb 2010
Service Output
– In-Out Pattern for a GET return (message)
OpenSG Service Definition, Feb 2010
Service Output
– In-Out Pattern for a POST return (ack)
OpenSG Service Definition, Feb 2010
Summary
– Definition using WSDL 2.0 (IRI style & InOut pattern)
– URL naming pattern (to follow XSD XPath)
– SLA on services such as limited return data
size
– Return data in XSD format (CIM based)
– GET for non state change and POST for
state change
OpenSG Service Definition, Feb 2010
Questions & Comments
OpenSG Service Definition, Feb 2010