Learning Objectives
- Understand at a high level the difference between Simple Object Access Protocol (SOAP) and REST for CIM messaging
- Understand at a high level the difference between XML and JavaScript Object Notation (JSON) for CIM messaging
- Understand the pros and cons of when to use SOAP/REST with XML/JSON payloads
RESTful and SOAP Web Services
The CIM is solely an information model and can be implemented in various ways. One prevalent method for machine-to-machine data exchange is through web services, with two primary types: Simple Object Access Protocol (SOAP) and Representational State Transfer (REST).
SOAP is a messaging protocol that uses XML for the machine-to-machine message exchange. SOAP web services are contract-based, making use of Web Service Definition Language (WSDL) files and XML Schema Definition (XSD) files to define what messages can be exchanged. Desired for its security and language independence, SOAP can be used in both publish-subscribe and request-response messaging patterns.
The SOAP protocol can be more complex to both consume and create because of its required usage of WSDLs and XSDs. Many tools exist in multiple programming languages to assist with the development of these services, such as Microsoft’s svcutil and the Apache CXF49 framework.
For the purposes of exchanging messages using the CIM, IEC 61968-100 primarily focuses on using SOAP as the exchange message between two systems. The IEC 61968-100 standard defines a Header element that contains a noun (for example, MeterReading) and verb (for example, GET, CREATE, or DELETE) to address SOAP’s inability to use these Hypertext Transfer Protocol (HTTP) methods. This is because even though SOAP uses HTTP as one of its transports, SOAP is not limited to HTTP only. For a deeper dive into IEC 61968-100, see Section 11.
REST is an architectural style for designing applications that communicate over HTTP. Web services that follow this style are referred to as RESTful web services. The style is distinguished by treating every object as a (web) resource with a Uniform Resource Identifier (URI) and limiting the web service actions to HTTP methods—most frequently GET, PUT, POST, and DELETE. REST makes full use of all HTTP verbs: GET to retrieve data, POST to create an object, PUT or PATCH to modify an object, and DELETE to delete an object. Working within this seemingly limited framework can produce interfaces that are uniform, scalable, and able to handle the inherent unreliability of network traffic. RESTful web services can exchange payloads in a variety of different formats, such as XML, JSON, plaintext, and Hypertext Markup Language (HTML). However, most REST application programming interfaces (APIs) use JSON for incoming requests and outgoing replies. As a result, RESTful web services are usually faster than SOAP web services because of the lightweight nature of JSON compared with XML.
REST has no contract such as SOAP’s WSDL defining the web services’ supported operations, nor is an XSD or equivalent required to define the information being exchanged. It is, however, common for the information being sent to be compliant to either an XSD or JSON schema.
REST web services are considered more lightweight and usually have lower overhead when compared with SOAP web services. SOAP loses some speed because of its type checking against the contract, enforcing Web Services Security (WS-Security or WSS), if enabled, and then its markup of the response and header it generates in XML. With modern technology, however, the speed difference is often negligible in real time depending on the frequency and size of the messages being exchanged.
Footnotes
49 Apache CXF is a registered trademark of the Apache Software Foundation.
JSON Versus XML
Extensible Markup Language
XML is a markup language, both machine-readable and human-readable, that describes data in a self-descriptive way. XML can be used for both the storage and transportation of data, using tags such as those used in HTML. Unlike HTML, XML is designed to convey rather than display data. Also, unlike HTML, XML contains no pre-defined tags: it is up to the author to define tags.
XML is both hardware- and software-independent and is used in SOAP web services. General guidance on the CIM uses XML examples because of IEC 61968-100’s primary focus being on SOAP over HTTP or JMS. XML’s advantages include the following:
- Its attributes. XML uses attributes to display metadata about an object. JSON cannot do this without creating a new key-value pair object, which would then be read by the receiving program as another separate object.
- Its namespaces. Namespaces enable the reuse of the definitions—for example, data types from other documents. Namespaces can help prevent name conflicts from occurring, especially when multiple schema files are used together to define a payload.
- Its XML schemas. XML documents can be described using XSD. The schema definition defines elements and attributes that must, or can, be present in a document. In this way the XSD represents a contract that document consumers can use to validate the document and write code and processing logic.
JavaScript Object Notation
JSON is a lightweight, text-based data exchange format. It originated from the programming language after which it was named, JavaScript; however, JSON data can be written in any programming language. JSON data come in what is known as name/value pairs, with curly braces containing objects, commas separating different aspects of that data within the object, and square brackets containing arrays. Like XML, JSON is a programming language-independent data format, making it a popular choice to use in REST web services because of its lower overhead compared with XML. JSON’s advantages include the following:
- Its verbosity. JSON does not have closing tags like XML, making it more compact.
- Its readability. The lack of closing tags makes JSON more human-readable because of a lower amount of overall clutter. It also does not have nested attributes within a tag.
- Its speed. JSON is not only faster to process because of its smaller file size in comparison to XML but also because software libraries built to process JSON use less memory compared with those used to process XML. This advantage can be either great or negligible depending upon the application and the volume of data being transferred.
Like XML’s XSD, JSON also has a vocabulary that allows for the annotation and validation of JSON documents. The JSON Schema, however, is still in its draft standard, which is Draft 2020-12 as of this writing. JSON Schemas, like XSDs, define elements (their type, their cardinality, their enumerated value, and so forth) that must be present in a message.
Mapping CIM Message from XML to JSON
The CIM is not constrained to a specific data format; however, it may become necessary to convert CIM messages from their XML format to JSON. The following sections detail how that can be approached for a few different scenarios. Note that a full conversion is not always necessary except to preserve the integrity of the original message, because some parts of XML, such as namespaces, serve no purpose in JSON.
Sample Header Message
The following is a sample header message in XML and then its equivalent in JSON:
<Header>
<Verb>get</Verb>
<Noun>MeterReadings</Noun>
<Timestamp>2020-05-04T15:10:00Z</Timestamp>
</Header>
The equivalent in JSON would then be
"Header": {
"Verb": "get",
"Noun": "MeterReadings",
"Timestamp": "2020-05-04T15:19:00Z"
}
Arrays, Namespaces, and Attributes
Arrays in JSON use the bracket notation typically used for arrays in most programming languages. The following is an example of two meters in SOAP XML:
<Payload>
<MeterReadingsxmlns="http://iec.ch/TC57/2011/MeterReadings#">
<MeterReading>
<Meter>
<Names>
<name>metername1</name>
<name>metername2</name>
</Names>
</Meter>
<Readings>
<timeStamp>2020-10-04T14:00:00Z</timeStamp>
<value>2.71828</value>
<ReadingType ref = "0.0.0.1.1.1.12.0.0.0.0.0.0.0.0.3.72.0"/>
</Readings>
</MeterReading>
</MeterReadings>
</Payload>
The JSON equivalent to this message would have to make sure to handle both the attribute and reference slightly differently, like so:
{
"Payload": {
"MeterReadings": {
"@xmlns": "http://iec.ch/TC57/2011/MeterReadings#",
"MeterReading": [
{
"Meter": {
"Names": {
"name": ["metername1", "metername2"]
}
},
"Readings": {
"timeStamp": "2020-10-04T14:00:00Z",
"value": 2.71828,
"ReadingType": {
"@ref": "0.0.0.1.1.1.12.0.0.0.0.0.0.0.0.3.72.0"
}
}
}
]
}
}
}
These are direct mappings only. A true RESTful implementation would have no need for Part 100's Payload object and would have a Resource going straight to MeterReadings.
Security
With any web service that has a public-facing API, security should be a top concern. Although REST and SOAP web services support secure sockets layer (SSL), SOAP has an additional layer of support known as Web Services Security. SOAP has additional protocols on top of its underlying transport layer for reliable and secure delivery of messages. SOAP’s WS-Security protocol’s main purpose is to provide XML encryption to messages being sent. Another protocol, WS-Addressing, is a standardized way of including message routing data in SOAP headers instead of relying on network-level transport to communicate routing information. WS-ReliableMessaging is a protocol that allows messages to be reliably transferred between systems, regardless of software, system, or network failures.
Although SSL is typically enough for most use cases, some may require an added layer of protection.
Case Study
At Electric Innovation Utility, Jeff Kimble knows that his team does not have to stay locked into using SOAP for web services even though it is still in use today by legacy systems. His team already uses REST for internal services, and applying that that to enterprise communications should be an achievable goal. He realizes now that there are valid reasons to use SOAP for certain services, whereas others might work better using a RESTful architecture. He has learned that the CIM model not only allows for the use of other data formats but that conversion between the two is certainly feasible. In fact, he thinks he saw a tool for converting his XSD schemas into JSON schemas to help speed along the process.
Being at a utility, however, Jeff realizes that security is of utmost importance. Thankfully, REST offers all the security that HTTP itself has to offer, including SSL protection for conveying sensitive information. Although Jeff is leaning toward embracing JSON for this new endeavor, he takes solace in the fact that XML is still a viable transport for his upcoming REST implementations.
Additional Resources
The EPRI Enterprise Architecture and Integration project set has published the following research on best practices for web services management, versioning, and development:
Which is true when comparing SOAP and REST?
A
REST is more secure than SOAP
B
REST can only use JSON for its payload, whereas SOAP can only use XML
C
REST and SOAP are both protocols for transporting data
D
REST has less overhead and is much faster than SOAP
E
REST typically requires more bandwidth
D. REST typically requires more bandwidth
The payload for REST messages is:
A
XML
B
JSON
C
Plain text
D
HTML
E
All the above
F
None of the above
E. All the above
The primary payload for SOAP is:
A
XML
B
JSON
C
Plain text
D
HTML
E
All the above
F
None of the above
A. XML
True or false: The CIM series of standards only supports SOAP and XML.
A
True
B
False
B. False
SOAP might be the best option when a user needs:
A
More security
B
The ability to use multiple payloads besides XML
C
High scalability and performance
D
Both b and c
E
All the above
A. More security
REST might be the best option when a user needs:
A
More security
B
The ability to use JSON or XML for message payloads
C
High scalability and performance
D
Both b and c
E
All the above
D. Both b and c