Chapter 5

📖 REST and SOAP

The client-server model alone is not sufficient for the internet to function effectively. Instead, it requires a precise specification of the steps involved in the communication process between clients and servers. This is done via dedicated protocols that ensure security and correctness.

SOAP

SOAP (Simple Object Access Protocol) was the initial protocol that formalized the client-server interaction for the web in 1998. It was widely used in the early 2000s for web services and data exchange.

SOAP is complex and secure, with strict rules, and is often used in situations where high security and reliability are necessary, like banking.

Deep dive to SOAP

SOAP is a protocol that provides a standard way for computers to exchange information over a network, especially when reliability and security are critical.

SOAP messages are strictly formatted in XML, which defines the structure of the message and ensures that all parts of the communication are clearly defined. Every SOAP message has a specific structure: an envelope that contains the message, a header (for optional metadata), and a body (for the actual data).

SOAP can work over many lower-level network protocols, including HTTP, SMTP (for email), or even TCP. However, HTTP is the most common.

SOAP can be stateful or stateless. This means it can maintain a session across multiple requests (stateful) if needed, which can be important for complex transactions.

SOAP has built-in standards for security (like WS-Security) and error handling. For example, it can encrypt messages and support various authentication methods, making it more suitable for applications that handle sensitive data, such as financial transactions or health information.

It also has standards for things like message reliability and transaction management, which helps ensure that messages are delivered correctly and consistently, even if there are network problems.

SOAP is more reliable and formal due to its strict rules and built-in error handling. It is ideal for complex enterprise-level applications where ensuring every message is delivered and understood correctly is crucial.

It supports advanced security features and is often used in industries where data integrity and security are paramount, like finance, healthcare, and government.

REST

Over time, another more light-weight protocol gained popularity and became the preferred choice for FHIR: REST (Representational State Transfer), first published in 2000 in the dissertation of Roy Fielding.

In 2011, the REST architecture for interacting with the server and the server client model was just a decade old, but already very successful and outgrowing the old SOAP protocol.

REST was adapted as the main exchange mechanism in FHIR.

REST is the most widely used exchange mechanism in HL7® FHIR®1 and was the key to the success of HL7® FHIR®1, but it is not the only possible exchange paradigm. In this learning unit, you will learn about alternative options.

Deep dive to REST

REST (Representational State Transfer):

REST is an architectural style that defines a set of rules for creating web services (APIs). It allows different computer systems to talk to each other over the internet by using standard web protocols.

RESTful APIs use standard web methods like GET (to retrieve data), POST (to send new data), PUT (to update data), and DELETE (to remove data). These methods are part of the HTTP protocol, which is the same protocol used to browse websites.

REST is designed to be stateless, which means each request from a client (like a mobile app or a web browser) to the server is independent and does not rely on previous requests. This makes it scalable and easy to manage.

REST is flexible with data formats: it can use JSON (JavaScript Object Notation), XML (Extensible Markup Language), HTML, or even plain text. However, JSON is the most common because it is lightweight, easy to read, and works well with JavaScript, which is widely used in web development.

REST is easier to implement and use because it relies on the standard web protocols that developers are already familiar with.

It is more performance-efficient due to its stateless nature and the lightweight nature of JSON.

REST APIs are more adaptable and can quickly respond to changes, which makes them ideal for modern web services, mobile applications, and microservices.

Mataphorical Comparison of REST and SOAP

Sometimes REST and SOAP are compared like this: REST is like sending a quick, flexible text message - easy, fast, and adaptable. SOAP is like sending a formal letter - detailed, structured, and secure, but slower and more complex.

Basic technical Comparision of REST and SOAP
FeatureSOAPREST
Formality and Structure:SOAP is highly structured, with strict rules for how messages should be formatted and transmitted. This structure includes predefined standards for handling security, transactions, and messaging reliability. This makes SOAP heavier and more complex but also more reliable and secure for applications that require these features.REST is more flexible and simpler. It does not have built-in standards for things like security or transactions, so developers have more freedom to implement solutions in ways that best fit their needs.
Data FormatSOAP only uses XML for message formatting, which adds to its complexity. XML is a verbose format, meaning it takes more time and resources to process than JSON.REST can use multiple data formats (JSON, XML, HTML, etc.), but JSON is most common because it is faster to read, write, and transmit.
Use Cases:SOAP is best for situations where there is a need for high security, guaranteed message delivery, and formal communication rules, such as in banking, insurance, or government applications.REST is ideal for public APIs and web services where speed, simplicity, and flexibility are more important, such as social media platforms, weather apps, and e-commerce websites.
Why HL7® FHIR® chooses REST despite SOAP’s security expertise

Despite SOAP’s built-in security features, REST has become the preferred choice for HL7® FHIR®, because it offers greater flexibility, scalability, and ease of integration with modern web technologies. REST can achieve high levels of security using standard web protocols like HTTPS[^https], along with robust authentication and authorization methods such as OAuth 2.0, making it suitable for handling sensitive data while providing a more lightweight and adaptable solution compared to SOAP.

What is https?

HTTPS (HyperText Transfer Protocol Secure) encrypts data between your web browser and a website, ensuring that information is secure and protected from hackers. For REST APIs, HTTPS makes communication secure by encrypting requests and responses, protecting data from interception. This security enables REST to be used safely over the internet, even in scenarios where SOAP (Simple Object Access Protocol) was previously preferred for its security features

What is OAuth2?

OAuth 2.0 is a secure way for one app to access specific information or services from another app without needing your password; it works like a temporary, limited-use key that you can easily revoke anytime, keeping your main login details safe.

In summary, wile SOAP has built-in security features, RESTful APIs like those used in HL7® FHIR® maintain security through other means:

  • HTTPS for encrypted communication,

  • OAuth 2.0 and other modern authentication and authorization standards,

  • Digital signatures and data integrity checks,

  • Best practices and additional security layers implemented by organizations.

  1. HL7, FHIR and the FHIR [FLAME DESIGN] are the registered trademarks of Health Level Seven International and their use does not constitute endorsement by HL7. ↩︎ ↩︎