7.2.2: RESTful Web Services (REST and JSON)

REST and JSON

REST (Representational State Transfer) is an architectural style for designing networked applications, introduced by Roy Fielding in 2000 as part of his doctoral dissertation [8]. REST is not a protocol or standard but rather a set of principles that describe how web resources should be defined and addressed. A web service that adheres to these principles is called a RESTful web service. In practice, RESTful services use HTTP as the application protocol and leverage the HTTP methods (GET, POST, PUT, DELETE, etc.) to operate on resources identified by URLs.

Key principles of REST include:

• Resource Identification: Each piece of information (resource) is identified by a URI (Uniform Resource Identifier). For example, a resource representing an employee with ID 123 might be https://api.company.com/employees/123.
• Uniform Interface: The server provides a uniform way to interact with resources using standard HTTP methods:
  • GET to retrieve a representation of the resource,
  • POST to create a new resource (or perform an action),
  • PUT to update a resource,
  • DELETE to remove a resource, etc. The format of requests and responses is standardized (e.g., using standard status codes, HTTP headers, etc.).
• Statelessness: Each request from client to server must contain all the information needed to understand and process the request. The server does not keep client context between requests. This means every request is independent; if state needs to persist, it is kept on the client and re-sent or identified (e.g., via a token) with each request. Statelessness greatly simplifies scaling (any server can handle any request) and recovery (no session continuity needed on the server).
• Representation-oriented: Clients interact with resources by exchanging representations of those resources (hence Representational State Transfer). For example, the server might store an employee in a database, but it can send a representation in JSON or XML format to the client. The client can send updated representations to modify the resource. The exact format can vary (JSON is very common now, but XML or others can be used).
• Self-descriptive messages: Each message includes enough information to describe how to process it. For example, using media types (MIME types like application/json) to tell how to interpret the payload, using hypermedia links in responses to indicate possible next actions, etc.
• Cacheability: Responses from the server should indicate whether they are cacheable, to leverage HTTP caching where possible for performance.
• Layered System: The client doesn’t need to know if it’s communicating with an end server or an intermediary (load balancer, proxy, etc.). The calls and responses remain the same, enabling scalability via layered architectures.

Unlike SOAP, REST has no official standard or WSDL to describe it (although as we’ll see, OpenAPI has become a de facto standard for describing RESTful APIs) [13]. REST is more of an architectural philosophy. A service can be “more or less RESTful” depending on how rigorously it adheres to the constraints above. Many Web APIs labeled “REST” are actually pragmatic REST-like HTTP APIs (they may not implement hypermedia or might allow some stateful operations, etc.). The key point is that REST embraces the design of the web itself – it treats URLs as resources and HTTP verbs as actions, rather than inventing a new messaging layer on top of HTTP.

JSON vs. XML: Early RESTful services often still used XML (since XML was the dominant structured data format in the early 2000s), but the rise of JSON (JavaScript Object Notation) as a lightweight data format has made JSON the preferred choice for most REST APIs today. JSON is more compact than XML and maps naturally to data structures in many programming languages (especially to JavaScript objects, which made it ideal for web browser clients via AJAX). JSON’s simplicity contributes to REST APIs being less verbose than SOAP (SOAP’s XML envelope plus payload can be significantly heavier than a simple JSON response). For example, a SOAP response for a weather service might be a 500-byte XML, whereas a REST JSON response might be 150 bytes and easier to parse by JavaScript.

REST vs SOAP philosophy: REST is often seen as more flexible and lightweight compared to SOAP. SOAP requires a rigid XML format and envelope, and the service interface is fixed by WSDL. REST allows multiple content formats (JSON, XML, even binary like images or PDFs) and doesn’t require a single rigid schema for all operations (each resource can have its own representation). This flexibility makes it easier to evolve services over time. For instance, adding a new field in a JSON response doesn’t break clients that ignore unknown fields, whereas adding a new element in a strict SOAP XSD might be more tightly coupled.

Performance-wise, REST can be faster and more scalable than SOAP in many scenarios. SOAP messages are typically larger (due to XML verbosity and the envelope structure) and require XML parsing and SOAP processing. REST, especially with JSON, tends to involve less data overhead (no envelope, and JSON is concise) and benefits from HTTP infrastructure (like caching proxies). Indeed, a comparison:

• Message size: SOAP only uses XML, which is verbose; REST can use JSON which is generally smaller.
• Transport overhead: SOAP with HTTP requires wrapping in an HTTP POST request (often to a single endpoint for all operations) and specifying the SOAP action. REST uses simpler HTTP GET/POST to distinct URLs. One consequence: REST URLs can be bookmarked or accessed directly, whereas SOAP requests usually require a specialized client.
• Caching: RESTful GET responses can be cached by HTTP caches (if marked cacheable). SOAP calls (being POST by default) are typically not cacheable by intermediaries. This can make repeated data retrieval more efficient in REST.
• State: SOAP services can be designed to maintain state on the server (though they don’t have to). For example, a SOAP service might have a login operation that establishes a session for subsequent calls. REST is stateless by design, which simplifies horizontal scaling – any server can handle any request since no session affinity is needed.

Use cases and Adoption: REST has become the dominant style for web APIs, particularly for public services (e.g., social media APIs, cloud service APIs, mobile app backends). Reasons include its relative simplicity (developers can test it easily with a browser or curl), and alignment with web standards. For example, a mobile app might GET a JSON list of products from api.myshop.com/products – something easily done with a simple HTTP call. The same in SOAP would involve generating a SOAP request XML, etc., which is more cumbersome especially in lightweight environments.

Modern applications, such as microservices architectures, also favor REST (and its successor protocols like gRPC) for internal communication because it’s simple and scales well with containers and cloud infrastructure. That said, if an organization already has SOAP web services for, say, internal data exchange or legacy systems, those might remain in use. There’s also a middle ground with RESTful SOAP – some services expose both SOAP and REST endpoints for the same functionality (e.g., AWS initially provided both SOAP and REST interfaces for some services like S3, but eventually deprecated SOAP due to lack of need as everyone used REST).

Example: Twilio (a company we’ll discuss more later) provides a REST API to send SMS messages. To use it, a client makes an HTTP POST request to a URL like https://api.twilio.com/2010-04-01/Ac.../Messages.json with form parameters or JSON payload including the message text and destination number. The response is a JSON object representing the sent message (with status, SID, etc.). This simple interaction (one URL, one POST, one JSON response) exemplifies the straightforward nature of REST. In contrast, a hypothetical SOAP version would require constructing an XML with a <SendMessage> element, etc., and parsing an XML response.

In summary, SOAP vs REST can be seen as “protocol vs style”. SOAP is a protocol with an extensive standardization of how every message and operation is handled. REST is an architectural style that utilizes existing web protocols in a simpler way. Table 7.1 highlights some key differences:

Table 7.1 – Comparison of SOAP and REST Web Services

Both SOAP and REST can achieve the same end goal (exposing services to remote clients), but they take very different approaches. As a rule of thumb, use REST for cloud-native applications and public APIs, unless there’s a compelling reason to use SOAP (e.g., you need a feature from the WS-* stack or must integrate with a SOAP-only system). Many organizations with existing SOAP services have been wrapping them with RESTful interfaces or migrating to microservices with REST/gRPC, to better fit modern architectures.