Introduction to Web Services - Restful and SOAP

This tutorial will help you understand the basics of web services and the different kinds of web services - REST and SOAP.

You will learn

  • What is a web service?
  • What are the advantages of web services?
  • What are the different types of web services?
  • What are RESTful web services?
  • What are SOAP web services?

10 Step Reference Courses

Tools you will need

  • Maven 3.0+ is your build tool
  • Your favorite IDE. We use Eclipse.
  • JDK 1.8+

What is a Web Service?

Service delivered over the web

Is this really a complete definition. Is everything thats delivered over the web “Web Service”?

Let’s consider a web application we developed for our Spring MVC Course to manage todo’s.


Is this application a web service?

Nope. The answer is no. This is a web application. Not a web service.

We are back to square one.

  • What is a web service?
  • How is it different from a web application?

To understand this, lets consider an example.

Mark Zuckerberg likes the web application we developed to manage todo’s. He thinks that our todo application is a right fit to integrate into facebook to manage todo’s. Can we use the existing application to do the integration? No.

Why? Because the existing application is designed for humans - other individuals. The output of the application is html which is rendered by browser to the end user. This is not designed for other applications.

What would be the difference in my thinking if I want to design the todo application so that other applications can interact with it?

I would need to produce the output in the format that the consumers can understand. Then facebook can call my web service and integrate it.

That leads use to - W3C definition of a Web Service

Software system designed to support interoperable machine-to-machine interaction over a network.

The key things to understand is

  • Web services are designed for machine-to-machine (or application-to-application) interaction
  • Web services should be interoperable - Not platform dependent
  • Web services should allow communication over a network

Web Service Data Exchange Formats

Facebook wants to talk to Todo Application

  • Facebook is built on a variety of languages - PHP is used for the front-end, Erlang is used for Chat, Java and C++ are also used.
  • Todo Application is build on Java using Spring MVC

You can see that Facebook and the Todo Application use different implementation technologies. However, we would want them to talk to each other as shown in the picture below:


Both applications should be able to understand the request and response.

So, what formats should we use for the request and response?

They should be standard formats so that they can be used with varied kind of platforms. JSON and XML are quite popular Data Exchange formats.

Types of Web Services

Not really types but a broad classification

  • SOAP
  • REST

These are not really mutually exclusive. Some SOAP services can actually be RESTful. So, the question is:

When does a web service become a SOAP Web service or a RESTful web service?


SOAP was earlier an abbreviation for Simple Object Access Protocol. In SOAP, the request and response are in XML format. However, not all types of XML are valid SOAP Requests.

SOAP defines a standard XML format. We will use WSDL (Web Service Definition Language) to define the format of request xml and the response xml.

Now lets say Facebook wants to know how to call the TODO Service? What should I give to the Facebook developer?

I will give him a WSDL of the Todo service. It will explain:

  • What are the different services (operations) exposed by the server?
  • How can a service (operation) be called? What url to use? (also called End Point).
  • What should the structure of request xml?
  • What should be the structure of response xml?

SOAP format defines a SOAP-Envelope which envelopes the entire document.

  • SOAP-Header (optional) contains any information needed to identify the request. Also, part of the Header is authentication, authorization information (signatures, encrypted information etc).
  • SOAP-Body contains the real xml content of request or response.
  • In case of error response, server responds back with SOAP-Fault.

Isn’t that cool?


First of all, REST does not define a standard message exchange format. You can build REST services with both XML and JSON. However, JSON is a more popular format with REST.

So, if it does not define a standard message exchange format, what is REST then?

REST is a style of software architecture for distributed hypermedia systems

REST stands for REpresentational State Transfer. The definitions for REST can be vague. So, lets understand the important concepts.

Key abstraction in REST is a Resource. There is no restriction on what can be a resource. A todo is a resource. A person on facebook is a resource.

A resource has an URI (Uniform Resource Identifier):

  • /user/Ranga/todos/1
  • /person/Ranga

A resource will have representations

  • XML
  • HTML
  • JSON

A resource will have state. The representation of a resource should capture its current state.

When a resource is requested, we provide the representation of the resource.


REST builds on top of HTTP (Hypertext Transfer Protocol). HTTP is the language of the web.

HTTP has a few important verbs.

  • POST - Create a new resource
  • GET - Read a resource
  • PUT - Update an existing resource
  • DELETE - Delete a resource

HTTP also defines standard response codes.

  • 200 - SUCESS
  • 400 - BAD REQUEST
  • 201 - CREATED
  • 415 - UNSUPPORTED TYPE - Representation not supported for the resource
  • 500 - SERVER ERROR

Restful Service Constraints

  • Client - Server : There should be a service producer and a service consumer.
  • The interface (URL) is uniform and exposing resources. Interface uses nouns (not actions)
  • The service is stateless. Even if the service is called 10 times, the result must be the same.
  • The service result should be Cacheable. HTTP cache, for example.
  • Service should assume a Layered architecture. Client should not assume direct connection to server - it might be getting info from a middle layer - cache.

Richardson Maturity Model

Richardson Maturity Model defines the maturity level of a Restful Web Service. Following are the different levels and their characteristics.

  • Level 0 : Expose SOAP web services in REST style. Expose action based services (http://server/getPosts, http://server/deletePosts, http://server/doThis, http://server/doThat etc) using REST.
  • Level 1 : Expose Resources with proper URI’s (using nouns). Ex: http://server/accounts, http://server/accounts/10. However, HTTP Methods are not used.
  • Level 2 : Resources use proper URI’s + HTTP Methods. For example, to update an account, you do a PUT to . The create an account, you do a POST to . Uri’s look like posts/1/comments/5 and accounts/1/friends/1.
  • Level 3 : HATEOAS (Hypermedia as the engine of application state). You will tell not only about the information being requested but also about the next possible actions that the service consumer can do. When requesting information about a facebook user, a REST service can return user details along with information about how to get his recent posts, how to get his recent comments and how to retrieve his friend’s list.

Designing RESTful APIs

Following are the important things to consider when designing RESTful API’s:

  • While designing any API, the most important thing is to think about the api consumer i.e. the client who is going to use the service. What are his needs? Does the service uri make sense to him? Does the request, response format make sense to him?
  • In Rest, we think Nouns (resources) and NOT Verbs (NOT actions). So, URI’s should represent resources. URI’s should be hierarchical and as self descriptive as possible. Prefer plurals.
  • Always use HTTP Methods.
    • GET : Should not update anything. Should be idempotent (same result in multiple calls). Possible Return Codes 200 (OK) + 404 (NOT FOUND) +400 (BAD REQUEST)
    • POST : Should create new resource. Ideally return JSON with link to newly created resource. Same return codes as get possible. In addition : Return code 201 (CREATED) is possible.
    • PUT : Update a known resource. ex: update client details. Possible Return Codes : 200(OK)
    • DELETE : Used to delete a resource.


REST vs SOAP are not really comparable. REST is an architectural style. SOAP is a message exchange format.

Let’s compare the popular implementations of REST and SOAP styles.

  • RESTful Sample Implementation : JSON over HTTP
  • SOAP Sample Implementation : XML over SOAP over HTTP

Following are the important things to consider:

  • REST is built over simple HTTP protocol. SOAP services are more complex to implement and more complex to consume.
  • REST has better performance and scalability. REST reads can be cached, SOAP based reads cannot be cached.
  • REST permits many different data formats (JSON is the most popular choice) where as SOAP only permits XML.
  • SOAP services have well defined structure and interface (WSDL) and has a set of well defined standards (WS-Security, WS-AtomicTransaction and WS-ReliableMessaging). Documentation standards with REST are evolving(We will use Swagger in this course).

Advantages of Web Services

  • Reuse : Mark Zuckerberg does not need to invest to build a todo application of his own.
  • Modularity
  • Language Neutral

Webservices form the building blocks of SOA and microservices architectures.

SOAP Service Examples


<Envelope xmlns="">
        <getCourseDetailsRequest xmlns="">


<SOAP-ENV:Envelope xmlns:SOAP-ENV="">
        <ns2:getCourseDetailsResponse xmlns:ns2="">
                <ns2:description>10 Steps</ns2:description>


<SOAP-ENV:Envelope xmlns:SOAP-ENV="">
            <faultstring xml:lang="en">java.lang.NullPointerException</faultstring>


  • view-source:http://localhost:8080/ws/courses.wsdl
<?xml version="1.0" encoding="UTF-8" standalone="no"?><wsdl:definitions xmlns:wsdl="" xmlns:sch="" xmlns:soap="" xmlns:tns="" targetNamespace="">
    <xs:schema xmlns:xs="" elementFormDefault="qualified" targetNamespace="">

    <xs:element name="getCourseDetailsRequest">
                <xs:element name="id" type="xs:string"/>

    <xs:element name="getCourseDetailsResponse">
                <xs:element name="course" type="tns:course"/>

    <xs:complexType name="course">
            <xs:element name="id" type="xs:string"/>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="description" type="xs:string"/>
  <wsdl:message name="getCourseDetailsRequest">
    <wsdl:part element="tns:getCourseDetailsRequest" name="getCourseDetailsRequest">
  <wsdl:message name="getCourseDetailsResponse">
    <wsdl:part element="tns:getCourseDetailsResponse" name="getCourseDetailsResponse">
  <wsdl:portType name="CoursesPort">
    <wsdl:operation name="getCourseDetails">
      <wsdl:input message="tns:getCourseDetailsRequest" name="getCourseDetailsRequest">
      <wsdl:output message="tns:getCourseDetailsResponse" name="getCourseDetailsResponse">
  <wsdl:binding name="CoursesPortSoap11" type="tns:CoursesPort">
    <soap:binding style="document" transport=""/>
    <wsdl:operation name="getCourseDetails">
      <soap:operation soapAction=""/>
      <wsdl:input name="getCourseDetailsRequest">
        <soap:body use="literal"/>
      <wsdl:output name="getCourseDetailsResponse">
        <soap:body use="literal"/>
  <wsdl:service name="CoursesPortService">
    <wsdl:port binding="tns:CoursesPortSoap11" name="CoursesPortSoap11">
      <soap:address location="http://localhost:8080/ws"/>

Congratulations! You are reading an article from a series of 50+ articles on Spring, Spring Boot , Hibernate, Full Stack, Cloud and Microservices. We also have 20+ projects on our Github repository. For the complete series of 50+ articles and code examples, click here.

Join 300,000 Learners!

Learn Spring Boot in 10 Steps - FREE Course

Next Steps















Related Posts

Spring Boot Tutorials for Beginners

At in28Minutes, we are creating a number of tutorials with videos, articles & courses on Spring Boot for Beginners and Experienced Developers. This resources will help you learn and gain expertise at Spring Boot.

Spring and Spring Boot Video Tutorials for Beginners

At in28Minutes, we are creating a number of tutorials with videos, articles & courses on Spring Boot for Beginners and Experienced Developers. Here's a list of video tutorials and courses for you

Creating Spring Boot and Vue JS CRUD Full Stack Application with Maven

This guide helps you create a full stack application with all the CRUD (Create, Read, Update and Delete) features using Vue JS as Frontend framework and Spring Boot as the backend REST API. We use Maven as the build tool.

Software Design - Separation Of Concerns - with examples

Software architects and programmers love having Seperation of Concerns. What is it? Why is it important? Let's get started.

Object Oriented Software Design - Solid Principles - with examples

Software design is typically complex. Object oriented design takes it to the next level. There are a number of design patterns and other stuff to be aware of. Can we make things simple? What are the goals to aim for when you are doing object oriented design? SOLID Principles is a great starting point for Object Oriented Design.

Software Design - Open Closed Principle - with examples

Open Closed Principle is one of the SOLID Principles. You want your code to be easily extended. How do you achieve it with minimum fuss? Let's get started.

Software Design - What is Dependency Inversion Principle?

Dependency Inversion Principle is one of the important SOLID Principles. Dependency Inversion Principle is implemented by one of the most popular Java frameworks - Spring. What is it all about? How does it help you design good applications?

Introduction to Four Principles Of Simple Design

With agile and extreme programming, the focus is on keeping your design simple. How do you keep your design simple? How do you decide whether your code is good enough?

Software Design - Single Responsibility Principle - with examples

For me, Single Responsibility Principle is the most important design principle. What is Single Responsibility Principle? How do you use it? How does it help with making your software better? Let's get started.

What is an In Memory Database?

In this article, we understand what the term "In-Memory Database" actually means. We see what scenarios they can be used, and why they are important.