JakartaJEEWebDevelopment

Jakarta JEE8 Enterprise Web Development

View on GitHub

REST Provides a Simpler Approach

REST Overview

REST (Representational State Transfer) services differ from SOAP in several key aspects:

  1. Client and Server:
    • Like SOAP, REST also consists of clients and servers. Clients initiate requests, and servers process these requests and return resources.
  2. Resource and Data Format:
    • REST services do not require you to specify the resource format and layout in advance. Resources in REST can be any type of data, including JSON, XML, or plain text, and are not bound to a specific protocol like SOAP’s WSDL.
  3. HTTP Verbs and MIME Types:
    • REST uses standard HTTP verbs for actions and MIME types to represent the resource types. The main CRUD (Create, Read, Update, Delete) operations in REST map to the following HTTP methods:
      • Create: POST - This method is used to create a new resource on the server.
      • Read: GET - This method retrieves a resource or a collection of resources from the server.
      • Update: PUT - This method updates an existing resource on the server.
      • Delete: DELETE - This method deletes a resource from the server.

    These HTTP methods facilitate interaction with resources on the server.

  4. Protocol and Content-Type:
    • Unlike SOAP, which uses a predefined WSDL envelope, REST utilizes the HTTP protocol directly. The Content-Type header in REST requests and responses indicates the type of data being sent or received, allowing flexibility in the data formats used.

MIME Types

MIME (Multipurpose Internet Mail Extensions) types are used to specify the nature and format of a document. In the context of REST APIs, MIME types indicate the format of the data being sent to and received from the server. Common MIME types include:

HTTP Status Codes

HTTP status codes are issued by a server in response to a client’s request. They indicate whether the request was successful or if there were any errors. Commonly used status codes include:

Discovering REST Endpoints: An Example

To interact with a REST API, you need to know the available endpoints. Here is a simple example of how you might discover and interact with REST endpoints using the GET method:

  1. API Endpoint Discovery

    Suppose you are provided with a base URL for an API: https://api.example.com/. You might start by discovering the available resources using the GET method:

    GET /api.example.com/

    Response:

    {
  "endpoints": {
    "users": "/users",
    "posts": "/posts",
    "comments": "/comments"
  }
}

  2. Accessing a Resource

    To get a list of users, you would use the GET method on the /users endpoint:

    GET /api.example.com/users

    Response:

    {
  "users": [
    {"id": 1, "name": "John Doe"},
    {"id": 2, "name": "Jane Smith"}
  ]
}

  3. Creating a Resource

    To create a new user, you would use the POST method:

    POST /api.example.com/users
Content-Type: application/json

{
  "name": "Alice Johnson"
}

    Response:

    HTTP/1.1 201 Created
Location: /api.example.com/users/3

  4. Updating a Resource

    To update an existing user, you would use the PUT method:

    PUT /api.example.com/users/3
Content-Type: application/json

{
  "name": "Alice Williams"
}

    Response:

    HTTP/1.1 200 OK

  5. Deleting a Resource

    To delete a user, you would use the DELETE method:

    DELETE /api.example.com/users/3

    Response:

    HTTP/1.1 204 No Content

5. Independence from Data Format

6. Discoverability with HATEOAS

Summary

REST and SOAP are both vital web service protocols, but they have different approaches and benefits. REST’s use of standard HTTP methods, flexibility in data formats, and discoverability through HATEOAS make it a versatile and agile choice for modern web and cloud-based applications. In contrast, SOAP’s structured and protocol-heavy approach is suitable for scenarios requiring strict standards and security.

These differences highlight why REST is often preferred in agile and cloud-based development environments, providing a more straightforward, flexible, and scalable solution compared to SOAP.

References