SOAP Vs REST
SOAP – SOAP is a protocol which was designed before REST and came into the picture. The main idea behind designing SOAP was to ensure that programs built on different platforms and programming languages could exchange data in an easy manner.
REST – This was designed specifically for working with components such as media components, files, or even objects on a particular hardware device. Any web service that is defined on the principles of REST can be called a RestFul web service. A Restful service would use the normal HTTP verbs of GET, POST, PUT and DELETE for working with the required components.
- SOAP stands for Simple Object Access
Protocol
- REST stands for Representational State
Transfer
- SOAP is a protocol. SOAP was designed with a
specification. It includes a WSDL file which has the required
information on what the web service does in addition to the location of
the web service.
- REST is an Architectural style in which a
web service can only be treated as a RESTful service if it follows the
constraints of being
- SOAP cannot make use of REST since SOAP is a
protocol and REST is an architectural pattern.
- REST can make use of SOAP as the underlying
protocol for web services, because in the end it is just an
architectural pattern.
SOAP
|
REST
|
1.
Client Server
2.
Stateless
3.
Cacheable
4.
Layered System
5.
Uniform Interface
|
|
Resource-oriented Architecture
In information technology, architecture refers to the overall structure of an information
system and the interrelationships of entities that make up that system. ROA is
considered a RESTful architecture. REST (representational state transfer) is defined by Roy
Fielding, co-author of the HTTP specification and co-founder of the Apache HTTP server
project, as an architectural style that exploits the existing technology and
protocols of the Web, including HTTP and XML.
Within the ROA concept, resources include not only IT infrastructure elements such as servers, computers and other devices, but also Web pages, scripts, and JSP/ASP pages, and other entities such as traffic lights.
Fielding’s doctoral dissertation, “Architectural Styles and the Design of Network-based Software Architectures,” identifies four essential concepts underlying the resource-oriented architecture:
- Resources
- Their names (URIs)
- Their representations
- The links between them.
and four properties:
- Addressability
- Statelessness
- Connectedness
- A uniform interface
“representations” in REST style
In REST-speak, a client and server exchange representations of a resource, which reflect its current state or its desired state. REST, or Representational state transfer, is a way for two machines to transfer the state of a resource via representations.
REST Architectural Constraints
REST stands for Representational State Transfer, a term coined by Roy Fielding in 2000. It is an architecture style for designing loosely coupled applications over HTTP, that is often used in the development of web services. REST does not enforce any rule regarding how it should be implemented at lower level, it just put high level design guidelines and leave you to think of your own implementation.
In my last employment, I designed RESTful APIs for telecom major company for 2 good years. In this post, I will be sharing my thoughts apart from normal design practices. You may not agree with me on a few points, and that’s perfectly OK. I will be happy to discuss anything from you with an open mind.
Let’s start with standard design specific stuff to clear what ‘Roy Fielding’ wants us to build. Then we will discuss my stuff which will be more towards finer points while you design your RESTful APIs.
Architectural Constraints
REST defines 6 architectural constraints which make any web service – a true RESTful API.
Elements of
REST style
Rest style is an abstraction of the
architectural elements within a distributed hypermedia system. REST
distinguishes three classes of architectural elements, they are:
- Connectors
- Components
- Data Elements
Connectors
Connectors represent the activities
involved in accessing resources and transferring representations. Roles provide
an interface for components to implement. REST encapsulates different
activities of accessing and transferring representations into different
connector types.
Components
In REST, the various software that
interacts with one another are called components
Data Elements
The key aspect of REST is the state of
the data elements, its components communicate by transferring representations
of the current or desired state of data elements. REST identifies six data
elements: a resource, resource identifier, resource metadata, representation,
representation metadata, and control data.
RESTful API
A RESTful API is an application
program interface (API) that
uses HTTP requests to GET, PUT, POST and DELETE data. The REST used by browsers can be
thought of as the language of the internet. With cloud use on the rise, APIs are emerging to expose web services.
Web API
HTTP ‘APIs’ are becoming increasingly more important with the
rise of the many devices in use today. Most mobile devices like phones and
tablets run Apps that are using data retrieved from the Web over HTTP. Desktop
applications are also moving in this direction with more and more online
content and syncing moving into even traditional desktop applications. The
pending Windows 8 release promises an app like platform for both the desktop
and other devices, that also emphasizes consuming data from the Cloud.
Difference between MVC and Web API
There are many differences between MVC and Web API, including:
- We can use the MVC for developing the
Web application that replies as both data and views but the Web API is
used for generating the HTTP services that replies only as data.
- In the Web API the request performs tracing
with the actions depending on the HTTP services but the MVC request
performs tracing with the action name.
- The Web API returns the data in various
formats, such as JSON, XML and other format based on the accept header of
the request. But the MVC returns the data in the JSON format by using
JSONResult.
- The Web API supports content negotiation, self
hosting. All these are not supported by the MVC.
- The Web API includes the various features of
the MVC, such as routing, model binding but these features are different
and are defined in the "System.Web.Http" assembly. And the MVC
features are defined in the “System.Web.Mvc" assembly.
- The Web API helps the creation of RESTful
services over the .Net Framework but the MVC does not support.
Implementations of JAX-RS include:
·
Apache CXF, an open source Web
service framework.
·
Jersey, the reference implementation from Sun (now Oracle)
·
RESTeasy, JBoss's implementation.
·
Restlet.
·
WebSphere Application Server from IBM
·
WebLogic Application Server from Oracle, see notes.
Everrest, Codenvy's Implementation.
Implementations of JAX-RS
include:
·
Apache CXF, an open source Web service framework
·
Jersey,
the reference implementation from Sun (now Oracle)
·
RESTeasy, JBoss's implementation
·
Restlet
·
WebSphere Application Server from IBM:
·
Version 7.0: via the "Feature
Pack for Communications Enabled Applications"
·
Version 8.0 onwards: natively
·
WebLogic Application Server from Oracle, see notes
·
Apache Tuscany (http://tuscany.apache.org/documentation-2x/sca-java-bindingrest.html),
discontinued
·
Cuubez framework (http://www.cuubez.com)
·
Everrest,
Codenvy's Implementation
·
Jello-Framework,
Java Application Framework optimized for Google App Engine, including a
powerful RESTful engine and comprehensive Data Authorization model.
RESTful Web
Service - JAX-RS Annotations
Annotation
|
Package Detail/Import statement
|
import javax.ws.rs.GET;
|
|
import javax.ws.rs.Produces;
|
|
import javax.ws.rs.Path;
|
|
import javax.ws.rs.PathParam;
|
|
import javax.ws.rs.QueryParam;
|
|
import javax.ws.rs.POST;
|
|
import javax.ws.rs.Consumes;
|
|
import javax.ws.rs.FormParam;
|
|
import javax.ws.rs.PUT;
|
|
import javax.ws.rs.DELETE;
|
|
@GET
Annotate your Get request methods with @GET.
1
2
3
4
|
@GET
public String getHTML() {
...
}
|
@Produces annotation specifies the type of output
this method (or web service) will produce.
1
2
3
4
5
|
@GET
@Produces("application/xml")
public Contact getXML() {
...
}
|
1
2
3
4
5
|
@GET
@Produces("application/json")
public Contact getJSON() {
...
}
|
@Path annotation specify the URL path on which this
method will be invoked.
1
2
3
4
5
6
|
@GET
@Produces("application/xml")
@Path("xml/{firstName}")
public Contact getXML() {
...
}
|
We can bind REST-style URL parameters to method
arguments using @PathParam annotation as shown below.
1
2
3
4
5
6
7
|
@GET
@Produces("application/xml")
@Path("xml/{firstName}")
public Contact getXML(@PathParam("firstName")
String firstName) {
Contact contact = contactService.findByFirstName(firstName);
return contact;
}
|
1
2
3
4
5
6
7
|
@GET
@Produces("application/json")
@Path("json/{firstName}")
public Contact getJSON(@PathParam("firstName")
String firstName) {
Contact contact =
contactService.findByFirstName(firstName);
return contact;
}
|
Request parameters in query string can be accessed
using @QueryParam annotation as shown below.
1
2
3
4
5
6
7
|
@GET
@Produces("application/json")
@Path("json/companyList")
public CompanyList getJSON(@QueryParam("start")
int start,
@QueryParam("limit") int limit) {
CompanyList list =
new CompanyList(companyService.listCompanies(start,
limit));
return list;
}
|
The example above returns a list of companies (with
server side pagination) which can be displayed with rich clients implemented
using Ext-js or jQuery. You can read more more about setting up ExtJS
grid panel with remote sorting and pagination using Hibernate.
@POST
Annotate POST request methods with @POST.
1
2
3
4
5
6
|
@POST
@Consumes("application/json")
@Produces("application/json")
public RestResponse<Contact> create(Contact
contact) {
...
}
|
The @Consumes annotation is used to specify the
MIME media types a REST resource can consume.
1
2
3
4
5
6
7
|
@PUT
@Consumes("application/json")
@Produces("application/json")
@Path("{contactId}")
public RestResponse<Contact> update(Contact
contact) {
...
}
|
The REST resources will usually consume XML/JSON@QueryParam annotation.
1
2
3
4
5
|
@POST
public String save(@FormParam("firstName")
String firstName,
@FormParam("lastName")
String lastName) {
...
}
|
Annotate PUT request methods with @PUT.
1
2
3
4
5
6
7
|
@PUT
@Consumes("application/json")
@Produces("application/json")
@Path("{contactId}")
public RestResponse<Contact> update(Contact
contact) {
...
}
|
Annotate DELETE request methods with @DELETE.
1
2
3
4
5
6
|
@DELETE
@Produces("application/json")
@Path("{contactId}")
public RestResponse<Contact>
delete(@PathParam("contactId") int contactId) {
...
}
|
There are two main implementation
of JAX-RS API.
- Jersey
- RESTEasy
Jersey framework is more than the JAX-RS Reference
Implementation. Jersey provides its own API that extend the JAX-RS toolkit. It provides additional features and
utilities to further simplify RESTful service and client development. Jersey
also exposes numerous extension SPIs so that developers may extend Jersey to
best suit their needs.
RESTEasy provides various framework to build RESTful Web
Services and RESTful Java applications. It is a fully certified and portable
implementation of the JAX-RS 2.1 specification, a JCP specification that
provides a Java API for RESTful Web Services over the HTTP protocol.
Annotation
|
Description
|
Path
|
It identifies the URI path. It can be specified on class or
method.
|
PathParam
|
Represents the parameter of the URI path.
|
GET
|
Specifies method responds to GET request.
|
POST
|
Specifies method responds to POST request.
|
PUT
|
Specifies method responds to PUT request.
|
HEAD
|
Specifies method responds to HEAD request.
|
DELETE
|
Specifies method responds to DELETE request.
|
OPTIONS
|
Specifies method responds to OPTIONS request.
|
FormParam
|
Represents the parameter of the form.
|
QueryParam
|
Represents the parameter of the query string of an URL.
|
HeaderParam
|
Represents the parameter of the header.
|
CookieParam
|
Represents the parameter of the cookie.
|
Produces
|
Defines media type for the response such as XML, PLAIN, and JSON
etc. It defines the media type that the methods of a resource class or
MessageBodyWriter can produce.
|
Consumes
|
It defines the media type that the methods of a resource class
or MessageBodyReader can produce.
|
All resource methods can
consume and produce content of almost any type. If you make a POST request to a
URI, such as api/books, the REST API expects the
HTTP body to contain a payload that represents the resource it should create.
This resource can be
represented using any media type. Although typically, it will be represented in
either, JSON or XML, but it could be
plain text, binary or a custom format. It doesn’t matter, as long as there is a
method in the resource class that can consume that media type.
In the header of the HTTP
request, there is a content-type field that specifies the media type and on the
other end, the server end, the resource class has a method annotated with the
matching type.
So, for example: If a
request has the content-type set to application/json the
resource method that consumes this request is the method annotated with the
same type, and likewise if the content type were application/xml the
method annotated with MediaType APPLICATION_XML would handle
that request.
Just as a method can
consume a payload of a given type, it can produce a response payload of a
specific media type too. In the case of a POST request, the created resource
can be returned back to the client. Conventionally, it is returned back in the
same format as it was received. So returns back as JSON,
if it was POSTed in JSON format, nevertheless, this
does not have to be the case.
There is another HTTP
header that specifies the accepted return media-type and there is a matching
annotation on the resource method also. Such a method would be annotated with the @Produces annotation and
passed the MediaType APPLICATION_JSON.
So a full example would be
an HTTP POST request with a content-type of JSON and
an accept type of JSON, and the
corresponding resource method would be annotated appropriately with both
a @Consumes and @Produces annotation
with the MediaType APPLICATION_JSON.
References:
https://whatis.techtarget.com/definition/resource-oriented-architecture-ROA
https://restfulapi.net/rest-architectural-constraints/
https://www.guru99.com/comparison-between-web-services.html#1
https://whatis.techtarget.com/definition/resource-oriented-architecture-ROA
https://restfulapi.net/rest-architectural-constraints/
https://www.guru99.com/comparison-between-web-services.html#1
https://restfulapi.net/rest-architectural-constraints/
https://www.guru99.com/comparison-between-web-services.html#1
https://www.javatpoint.com/jax-rs-annotations-example
https://readlearncode.com/java-ee/java-ee-working-with-jax-rs-consumes-and-produces/
