RESTful Service Discussions Shawn Hu Open SG Service

RESTful Service Discussions Shawn Hu Open. SG 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. w 3. org/ns/wsdl/style/iri" pattern="http: //www. w 3. org/ns/wsdl/in-out" – Binding type: • type="http: //www. w 3. org/ns/wsdl/http" – Operation method (http verbs) • whttp: method="GET" (or others) Open. SG Service Definition, Feb 2010

Consumption XML Schema • Consumption. xsd Open. SG Service Definition, Feb 2010

RESTful Service Definition • Input – Using HTTP GET or POST following URL naming convention • Output – Using XSD for return Open. SG Service Definition, Feb 2010

Xpath for URI Design http: //www. openade. org/datastore/Consumption/Meter. Reading/Interval. Blocks/Interval. Readings/value Open. SG 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/Meter. Reading/Interval. Blocks/Interval. Readings/ to access interval readings as consumption – <Request> - An optional field for arguments such as ? time. Stamp=2010 -02 -02 T 00: 00 Z – Example URI for a resource: http: //www. openade. org/datastore/Consumption/Meter. Reading/I nterval. Blocks/Interval. Readings? time. Stamp=2010 -0202 T 00: 00 Z Open. SG Service Definition, Feb 2010

Service Table Open. SG Service Definition, Feb 2010

GET URI & Return XML • Entry URI: http: //www. Open. SG. org/datastore/Consumption/Meter. Reading/Interval. Bloc ks/Interval. Readings/value? time. Stamp=2009 -12 -17 T 09: 30: 47 Z Note: <Resource Path> may need to truncated to only list <Immediate Parent><Child> such as http: //www. Open. SG. org/datastore/Interval. Readings/value? time. Stamp=200912 -17 T 09: 30: 47 Z • Return XML: <? xml version="1. 0" encoding="UTF-8"? > <m: Consumption> <m: Meter. Reading> <m: Interval. Blocks> <m: Interval. Readings> <m: time. Stamp>2009 -12 -17 T 09: 30: 47 Z</m: time. Stamp> <m: value>12. 35</m: value> </m: Interval. Readings> </m: Interval. Blocks> </m: Meter. Reading> </m: Consumption> Open. SG Service Definition, Feb 2010

POST Entry URI & XML • Entry URI: http: //www. Open. SG. org/datastore/Consumption/Meter. Reading/Interval. Bloc ks/Interval. Readings/value • Resulting XML to post: <? xml version="1. 0" encoding="UTF-8"? > <m: Consumption> <m: Meter. Reading> <m: Customer. Agreement> <m: m. RID>12345</m: m. RID> </m: Customer. Agreement> <m: Interval. Blocks> <m: Interval. Readings> <m: time. Stamp>2009 -12 -17 T 09: 30: 47 Z</m: time. Stamp> <m: value>12. 35</m: value> </m: Interval. Readings> </m: Interval. Blocks> </m: Meter. Reading> </m: Consumption> Open. SG 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><t. S>2009 -1217 T 09: 30: 47 Z</t. S><v>12. 35</v></IR></IB></MR></C> Open. SG Service Definition, Feb 2010

WSDL Design – Operation Style & Pattern • style=http: //www. w 3. org/ns/wsdl/style/iri (W 3 C WSDL 2. 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 local. Part 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: simple. Type, and MUST NOT be of the type or derive from xs: QName, xs: NOTATION, xs: hex. Binary or xs: base 64 Binary. † Note: IRIs – Internationalized Resource Identifiers (IETF) Open. SG Service Definition, Feb 2010

WSDL Design – Operation Style & Pattern • pattern=http: //www. w 3. org/ns/wsdl/in-out (W 3 C WSDL 2. 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. w 3. org/ns/wsdl/in -out". Open. SG Service Definition, Feb 2010

Service Output – In-Out Pattern for a GET return (message) Open. SG Service Definition, Feb 2010

Service Output – In-Out Pattern for a POST return (ack) Open. SG Service Definition, Feb 2010

Summary – Definition using WSDL 2. 0 (IRI style & In-Out 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 Open. SG Service Definition, Feb 2010

Questions & Comments Open. SG Service Definition, Feb 2010