API / Web services

A web service represents a collection of open protocols and standards used for exchanging data between applications. Software applications written in various programming languages and running on various platforms can use web services to exchange data over computer networks like the Internet in a manner similar to inter-process communication on a single computer.

REST (Representatonal state transfer) introduced by Roy Fielding in the 2000 defines web standards based architecture and uses HTTP Protocol for data communication. It revolves around resource where each component is a resource and a resource is accessed by a common interface using HTTP standard methods.

In REST architecture, a REST Server provides access to the resources and REST client accesses and presents these resources. Here each resource is identified by URIs/ global IDs. REST uses various representations formats like text, JSON and XML. JSON is the most popular format being used in web services nowadays.

REST supports different formats like text, JSON and XML whereas SOAP supports only XML.

REST works only over HTTP(S) on a transport layer while SOAP can be used with different protocols on a transport layer.

REST works with resources, each unique URL is some representation of a resource while SOAP works with operations, which implements some business logic through different interfaces.

SOAP based reads cannot be cached, need to provide caching for SOAP while REST based reads can be cached.

SOAP supports SSL security and WS-security(Web Service-security) while REST only supports SSL security.

SOAP supports ACID (Atomicity, Consistency, Isolation, Durability) while REST supports transactions, but it is neither ACID compliant nor can provide two phase commit. .

SOAP is preferred where service requires comprehensive support for security (WS-security) and transactional safety (ACID).

REST is preferred where sevice needs performance, scalability and support for multiple data formats.

WSDL (Web Services Description Language) is a XML document for describing web services and also describe how to access them.

JAX-WS (Java API for XML Web Services) is a set of APIs for creating web services in XML format. It is a Java programming language API for creating SOAP web services. JAX-WS is one of the Java XML programming APIs and is part of the Java EE platform.

JAXB (Java Architecture for XML Binding) is a Java standard that defines how Java objects are converted to and from XML. It facilitates reading and writing of XML using Java relatively simple.

Yes, we may send different formats such as PDF document, image or other binary file with soap messages as an attachment. Messages sent using the binary data. SOAP messages is attached with MIME extensions that come in multipart/related.

MTOM (Message Transmission Optimization Mechanism) is a mechanism for transmitting large binary attachments with SOAP messages as raw bytes, allowing for smaller messages.

XOP (XML-binary Optimized Packaging) is a mechanism for the serialization of XML Information Sets that contain binary data, as well as deserialization back into the XML Information Set.

SOAP envelope element is the root element of a SOAP message which defines the XML document as a SOAP message.

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
  ...
  Message information
  ...
</soap:Envelope>

SOAP encoding is a method for structuring the request which ips suggested within the SOAP specification, known as the SOAP serialization.

SOAP encodingStyle defines the serialization rules used in a SOAP message. This attribute may appear on any element, and is scoped to that element's contents and all child elements not themselves containing such an attribute.

There are no default encoding defined for a SOAP message.

• RPC (remote procedure call) style web service in JAX-WS.
• document style web service in JAX-WS.

• A header entry is identified by its fully qualified element name, which consists of the namespace URI and the local name. All immediate child elements of the SOAP Header element must be namespace-qualified.
• the SOAP encodingStyle attribute may be used to indicate the encoding style used for the header entries.
• the SOAP must understand attribute and SOAP actor attribute may be used to indicate how to process the entry and by whom.

The wsimport tool is used to parse an Web Services Description Language (WSDL) file and generate required files (JAX-WS portable artifacts) for web service client to access the published web services.

The wsgen tool is used to parse an existing web service implementation class and generates required files (JAX-WS portable artifacts) for web service deployment.

SOAPUI tool for SOAP WS, http://www.soapui.org/

SOAP is simple to use and it is non - symmetrical unlike DCOM or CORBA is highly popular and usually have complexity in them.

SOAP provides greater platform independent with the language independence unlike DCOM or CORBA doesn't provide any of these.

SOAP uses HTTP as its transport protocol and the data are being saved in XML format that can be ready by human, whereas DCOM or CORBA have their own binary formats that are used to transport the data in complicated manner.

SOAP identify the object other than URL endpoint. SOAP objects are stateless and it is hard to maintain that. Whereas, it is not hard to maintain in case of other remote access techniques.

A resource is an unique URL with representation of an object through which we can get contents via GET and modify via PUT, POST, DELETE.

• GET.
• POST.
• PUT.
• DELETE.
• OPTIONS.
• HEAD.

PUT is idempotent, while POST is not.

Calling the same PUT request multiple times will always produce the same result (no side effect), while on the other hand, calling a POST request repeatedly may have (additional) side effects of creating the same resource multiple times.

WADL (Web Application Description Language) is a XML description of a deployed RESTful web application.

Apache wink, Jersey, Restlet, EasyRest, etc.

In Ajax, the requests are sent to the server by using XMLHttpRequest objects; REST have a URL structure and a request/response pattern the revolve around the use of resources.

Ajax eliminates the interaction between the customer and server asynchronously; REST requires the interaction between the customer and server.

Ajax is a set of technology; REST is a type of software architecture and a method for users to request data or information from servers.

Firefox 'poster' plugin for RESTFUL services. Usually any browser would be sufficient to test JSON based rest services.

REST web services can be tested easily using curl commands and using other browser extensions. Resources supporting GET method can be tested with browser itself, without using any other programs.

@Path annotation binds URI pattern to a Java method.

@PathParam annotation injects the value of URI parameter that defined in @Path expression.

@QueryParam annotation injects URI query parameter into Java method.

The @MatrixParam annotation allows you to inject URI matrix paramters into your method In vocation. The matrix parameters are an arbitrary set of name-value pairs embedded in a uri path segment.

JAX-RS uses @QueryParam to access query string and @MatrixParam to aceess matrix parameter.

Matrix parameters apply to a particular path element while query parameters apply to the request as a whole.

@FormParam bind HTML form parameters value to a Java method.

Use @produces annotation with the appropriate MIME type to download the file. For example, In JAX-RS, to download a PDF, annotate the method with @Produces("application/pdf").

In document style web services, we can transport an XML message as part of the SOAP request whereas in RPC style web service it is not possible.

Document style web service is most appropriate in some application where XML message behaves as document and content of that document can alter and intention of web service does not rely on the content of XML message.

In top-down approach, WSDL document is created first and then the Java classes are developed based on WSDL contract, so if WSDL contract changes Java classes need to be changed as well.

In bottom up approach of web service development, Java code is created first and then annotations like @WebService is used to specify contract or interface and WSDL field will be automatically generated from the build.

REST represents REpresentational State Transfer, is an architectural style by which data can be transmitted over the transport protocol such as HTTP(S).

RESTFUL refers to any web service written using REST architectural concept.

SOA (Service-Oriented Architecture) is an architectural pattern that enables services to interact with one another independently.

Web Services is a realization of SOA concept, that leverages XML, JSON, etc. and common Internet protocols such as HTTP(S), SMTP,

• Directly accessing or sharing the database.
• Batch file transfer or sharing.
• Invoking remote procedure (RPC).
• Swapping asynchronous messages over a message oriented middle-ware (MOM).

Interoperability: Using web services, an application can communicate with other application developed in any language.

Reuability: We can expose the web service so that other applications can use it.

Modularity: Using web service, we can create a service for a specific task such as tax calculation etc.

Loosely Coupled Applications.

Standardized Protocol: Web services use standardized industry standard protocol for the communication. All the four layers (Service Transport, XML Messaging, Service Description, and Service Discovery layers) use well-defined protocols in the web services protocol stack. This standardization of protocol stack provides the business many advantages such as reduction in the cost, and increase in the quality.

UDDI (Universal Description, Discovery and Integration) is a XML based framework for describing, discovering and integrating web services.

UDDI is a directory of web service interfaces described by WSDL, containing information about web services.

It is a defined set of protocols that can be used to explore and execute web services. The entire stack consists of 4 layers, Service Transport, XML Messaging, Service Description and Service Discovery.

XML provides tagging and data formatting to the web service.

SOAP helps web service to transfer messages.

WSDL is used to describe the service and also ensure its availability.

The binding of a client to the execution of the service is referred as synchronicity. In synchronous invocations, the client halts and waits for the service to complete its operation before continuing. Asynchronous operations allow a client to invoke a service and then execute other functions.

• Network Security.
• Service authentication.
• Confidentiality.

We cannot have user sessions in web service as it is stateless.

We can create SOAP web services using JAX-WS API. Other frameworks include Apache Axis and Apache CXF.

Apache Axis and CXF are not implementations of JAX-WS API, frameworks that leverages Servlet model to expose your business logic classes as SOAP web services.

• @WebService.
• @SOAPBinding.
• @WebMethod.

WSDL document can be accessed by appending "?wsdl" to the SOAP endpoint URL.

This file helps providing the endpoints details when JAX-WS web services are deployed in servlet container such as Tomcat. This file is placed at WEB-INF directory and contains endpoint name, implementation class, URL pattern and other meta information.

• Supports WS-Security.
• Integrates with Acegi Security.
• Powerful mapping.
• XML API support.
• XML Marshalling.
• Maven support.

There are two web service development styles, Contract First and Contract Last. Spring-WS supports contract first approach.

contact first approach starts at WSDL contract and use Java to implement that contract. In case of contract last, start with Java code and let the web services to contract WSDL.

Contract first has good performance compared to the contract last approach as there is no need to generate xml from Java as in contact last.

Apache Axis is a web services framework that provides the implementation of JAX-RPC(Axis 1.x) and JAX-WS(Axis 2) web services specifications.

Web service uses an endpoint to transfer and receive messages between applications using HTTP protocol. It uses XML to encode data.

CORBA and DCOM enables communication between applications using non-standard protocols such as IIOP and RPC.

A SOAP message consists of SOAP Envelope, SOAP Headers, and SOAP Body.

The Richardson Maturity Model assesses your API according to the constraints of REST. Higher the score true RESTful API it is. The Richardson Maturity Model defines 4 levels (0-3), where level 3 designates a fully true RESTful API.

Level 0 : Expose SOAP web services in REST style. Expose action based services for example (http://server/getFavorites, http://server/deleteFavorites) using REST.

Level 1 :Create resources with proper URIs (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.

JSON is a simple data exchange format. JSON refers to JavaScript Object Notation; it is a language similar to XML and platform independent.

File extension of JSON is .json.

The MIME type for JSON text is ?application/json?.

An JSON object can be defined as an unordered set of name/value pairs. An object in JSON starts with {left brace} and ends with {right brace}. Every name is followed by: (colon) that precedes the value and the name/value pairs are parted by, (comma).

• Data is in name/value pairs.
• Each pair is separated by comma.
• Curly brackets hold objects.
• Square bracket represents arrays.

JSON parsing is faster than XML parsing.

JSON is a more compact and weigh less on the wire than the more verbose XML.

Formatted JSON is easily readable than formatted XML.

Easier to represent a null value in JSON.

JSON is easily consumed by JavaScript.

JSON is transportation-independent, you may bypass the XMLHttpRequest object for getting your data.

JSON object can hold functions (JavaScript for example) as well in addition to data.

JSONP, JSON with padding is a method used to bypass the cross-domain policies in web browsers.

JSONP is the simple way to deal with browser restrictions when sending JSON responses from different domains from the client.

JSONP is for cross-domain request, making requests to different domain while JSON is for same domain-same origin requests.

XML is stricter and has support for schemas and namespaces. Namespaces allow for sharing of standard structures.

Standard ways of expressing the structure of the document such as XML schema, DTD, etc.

Availability of Parsing standards like DOM and SAX.

Querying facility using XQuery and XPath.

Standards for transforming a document using XSLT.

Spring Web Services (Spring-WS) is a product of the Spring community focused on creating document-driven Web services. Spring Web Services aims to facilitate contract-first SOAP service development, allowing for the creation of flexible web services using one of the many ways to manipulate XML payloads.

The product is based on Spring itself, which means you can use the Spring concepts such as dependency injection as an integral part of your Web service.

The main modules are,

• XML module,
• Core module,
• Support module,
• and security module.

The XML module (spring-xml.jar) contains various XML support classes for Spring Web Services. This module is mainly intended for the Spring-WS framework itself, and not a Web service developers.

The Core module (spring-ws-core.jar) is the central part of the Spring's Web services functionality. It provides the central WebServiceMessage and SoapMessage interfaces, the server-side framework, with powerful message dispatching, and the various support classes for implementing Web service endpoints; and the client-side WebServiceTemplate.

The Support module (spring-ws-support.jar) contains additional transports (JMS, Email, and others).

The Security module (spring-ws-security.jar) provides a WS-Security implementation that integrates with the core Web service package. It allows you to add principal tokens, sign, and decrypt and encrypt SOAP messages. Additionally, it allows you to leverage your existing Spring Security security implementation for authentication and authorization.

No. Spring-WS only supports the contract-first development style.

When developing web services, there are two approaches:Contract Last and Contract First. Whan using the contract-last approach, you first write the Java code and let web service contract(WSDL) to be genereated for that. When using the contract-first approach, you start with the web services contract (XML files) and let Java implement the web service contract.

API acts as an interface between two different applications so that they can communicate with each other. An API is not necessarily web-based. API may use any means of communication to initiate interaction between applications.

Web service facilitates interaction between two machines over a network.Web service also uses SOAP, REST, and XML-RPC as a means of communication.

All Web services are APIs but all APIs are not Web services.

A Web service uses only three styles of use: SOAP, REST and XML-RPC for communication whereas API may use any style for communication.

A Web service always needs a network for its operation whereas an API doesn't need a network for its operation.

An WSDL document describes a web service. A WSDL document has a definitions element that contains the other five elements, types, message, portType, binding and service. The following sections describe the features of the generated client code:

types defines the (XML Schema) data types used by the web service.

message defines the data elements for each operation.

portType describes the operations that can be performed and the messages involved.

binding defines the protocol and data format for each port type.

service specifies the port address of the binding. The service is a collection of network endpoints or ports.

operation provides an abstract description of the action supported by the service.

RESTful web service will include CORS access control headers in its response, when you add a @CrossOrigin annotation to the handler method.

@CrossOrigin(origins = "http://localhost:9000")
    @GetMapping("/greeting")
    public Greeting greeting(@RequestParam(required=false, defaultValue="World") String name) {
        System.out.println("==== in greeting ====");
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }

@Produces annotation defines the endpoint's response type. @Consumes annotation defines the MIME media types that the service can consume.

The request data which is present in the body part of every HTTP message is referred as ‘Payload’. In Restful web service, the payload can only be passed to the recipient through POST method.

There is no limit for payload, however, more the size, will consume more resource and bandwidth.

No, the payload can only be passed using POST method.

Idempotent operations means their result will always same no matter how many times these operations are invoked.

PUT and DELETE operations are idempotent.

GET method is read only and safe.

This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

HEAD method is used to get only response status and headers information from the server but no body (entity). The HEAD method can be used to know, whether the resource exists on the server.

There are 2, SOAP (Simple Object Access Protocol) and REST (Representational State transfer) web services.

SOAP supports both POST and GET methods. However, POST is preferred according to the W3C standard.

The definition elements of WSDL are, types, messages, operations and porttype.

RESTful API Modeling Language (RAML) is a YAML-based language for describing RESTful APIs. It provides all the information that describes RESTful APIs.

It encourages reuse, enables discovery and pattern-sharing and aims for merit-based emergence of best practices.

JAX-RS provides the standard way for developing rest services. Apache Jersey, one of the JAX-RS implementation provides more specification and features. Other APIs include RESTEasy, RESTlet and Apache CFX.

There are many tools available to test rest services internally as well as externally by accessing through URL.

To test internally, JUNIT, mockito frameworks may used that unit tests on demand.

For external testing, use tools such as JMeter, Grinder, chrome plugin postman, SoapUI and RestClientUI.

Jersey framework is an open source framework for developing RESTful Web Services in Java. It provides support for JAX-RS APIs and serves as a JAX-RS (JSR 311 & JSR 339) Reference Implementation.

JAVA API for RESTful Web Services (JAX-RS), a JAVA programming language API is a specification to provide support for creating RESTful Web Services.

JAX-RS specification also supports creating clients for REST services.

It uses annotations introduced in Java 5 that simplifies the development and usage .

JAX-WS , a Java API for the XML-Based Web Services, provided a standard way to develop a Web Services in SOAP (Simple Object Access Protocol) notation.

In JAX-WS, Web Services are called/invoked through remote procedure calls. SOAP protocol is used to exchange of information between the client and the Web Service. Message exchange between the client and the server performed through XML based SOAP messages.

Clients of the JAX-WS Web Service need a WSDL file to generate executable code that the clients can use to call Web Service.

JAX-RS is a Java API for RESTful Web Services. RESTful Web Services are represented as resources and can be identified by Uniform Resource Identifiers (URI). Remote procedure call in this case is represented a HTTP- request and the necessary data is passed as parameters of the query. REST Web Services are more flexible, can use several different MIME- types. Typically used for XML data exchange or JSON (JavaScript Object Notation) data exchange.

A request consists of 4 parts.

• The endpoint,
• method,
• headers,
• and the data (or body).

JAX-RS is a specification for implementing REST web services in Java and its (JAX-RS) reference implementation include Jersey, RESTEasy and Apache CXF. JSR standard can be run without servlet container.

The Spring is a complete framework that creates Java enterprise applications. In Spring, the REST capabilities are provided by the Spring MVC module itself which is NOT a JAX-RS implementation. It may be considered as an alternate to the JAX-RS standard.

The below are some of the ways of securing a RESTful web service.

• Clients have the certificates that are trusted by the servers. The clients presents the trusted certificate on request.
• OAuth with HTTPS.
• HTTP Basic with HTTPS.
• API Key is provided to client and that API key defines which client is accessing the service.

According to stackoverflow, the statelessness of REST is designed to ensure applications scale well. You can add state, but it is at a trade-off in scalability.

We can make it stateful by applying session management technique such as,

• Cookies,
• Hidden form field,
• URL Rewriting,
• and HttpSession.

One of the common scenario to add state to REST is for authentication. Once a secure connection is established, a secure cookie can be sent to the client. This cookie is then added by the client to all requests for the session. The server maintains state and then loads that state in with every request based on the cookie.

Yes, it is stateless while FTP is stateful.

Web services, both REST and SOAP, are stateless by default. We may make it stateful if needed by applying session management techniques.

Yes. It is stateless however it can be programmatically converted to stateful.

JAX-WS is a specification however JAVA6 included a in-built JAX-WS implementation. Other reference implementations include apache CXF and Axis2.

The main advantage is that Apache CXF can produce both JAX RS and JAX WS implementations from the same data model and service interface.

CXF has good support for spring. It is a open source framework and support OSGI.

CXF supports complex feature such as WS-Security, WS-RM and WS-Policy.

There are 4 ways we can implement the behavior.

• Servlet filter,
• CXF Interceptor,
• JAX-RS Filter,
• perform the encode/decode(interception logic) within the actual service logic.

Apache Axis (Apache eXtensible Interaction System) is an open-source, XML based Web service framework.

Apache Axis framework provides implementation of JAX-RPC (Axis 1.x) and JAX-WS (Axis 2) web services specifications.

If an error occurs during processing at the server, the response to a SOAP message is a SOAP fault as an element in the body of the message, and the fault is returned to the sender of the SOAP message (client).

The SOAP fault mechanism returns specific information about the error that include a predefined code, a description, and the address of the SOAP processor that generated the fault.

If you are using Spring MVC, use Spring @ResponseStatus annotation to set HTTP Status code.

@ResponseStatus(HttpStatus.BAD_REQUEST, reason = "Object missing, unable to parse")
void onNullPointerException (NullPointerException e) {}

Web Services Security (WS Security) specification defines how security measures are implemented in web services to protect them from external attacks. It is a set of protocols that ensure security for SOAP-based messages by implementing the principles of confidentiality, integrity and authentication.

No, REST does not.However both REST and SOAP API formats support Secure Sockets Layer that protect data when it get transferred. SOAP, in addition to that, offer WS-Security thats an added advantage to enterprise applications.

The below ways define how to secure Web services running in a web container that conform to the Representational State Transfer (REST) architectural style using Java API for RESTful Web Services (JAX-RS).

• Updating the web.xml deployment descriptor to define security configuration (Basic authentication).
• Using the javax.ws.rs.core.SecurityContext interface to implement security programmatically.
• Applying annotations to your JAX-RS classes.
• Using Jersey OAuth libraries to sign and verify requests.

WS-Reliability is a specification for open, reliable Web services messaging, including guaranteed delivery, eliminating duplicate message and message ordering, that enables reliable communication between Web services.

The reliability features are based on extensions to the Simple Object Access Protocol (SOAP), rather than being tied to the underlying transport protocol. The specification will allow a variety of systems to interoperate reliably in a platform and vendor neutral manner.

The WS Reliability specification defines a set of SOAP headers, or instructions within the SOAP envelope, that govern the control of message acknowledgments, sequencing and message persistence.

As per Wikipedia, the SOAP with Attachments API for Java or SAAJ provides a standard way to send XML documents over the Internet from the Java platform.

SAAJ enables developers to produce and consume messages conforming to the SOAP 1.1 and 1.2 specifications and SOAP with Attachments note. It can be used as an alternative to JAX-RPC or JAX-WS.

The service endpoint interface (SEI) is a Java interface class that defines the methods to be exposed as a Web service.

Apigee Edge is a platform for developing and managing APIs. By fronting services with a proxy layer, Edge provides an abstraction or facade for your backend service APIs and provides security, rate limiting, quotas, analytics, and more.

I have used proxy layer of apigee Edge to process the response from API and route to end user.

XSD defines a schema which defines how an XML document can be structured. You can use it to check that a given XML document is valid and follows the rules you've laid out in the schema.

WSDL is an XML document that describes a web service. It shows which operations are available and how data should be structured to send to those operations.

WSDL documents have an associated XSD that show what is valid to put in a WSDL document.

Diagnostics and Forensics logging: Log service requests and provide a detailed report of who has invoked to find error conditions or to determine what occurred after a breach.

Security logging: Log all administrative activities, changes to privileges, add/removing/changing users and API keys, and so on.

Correlate Execution context: Provide a service feature level execution identity. Many different services may be handling one request. Logs are spread out and will be difficult to correlate all the SQL activities on a persistence service with users' original feature request.

Sensitive information: Do NOT log sensitive information like password and credit card numbers. This included your application code but also web application infrastructure logging.

Business logging: OWASP Security Logging offers some features to correlate your log message traffic.

RestTemplate class is an implementation of the Template method pattern in the Spring framework. It simplifies the interaction of RESTful Web Services on the client-side.

PUT is considered idempotent. When you PUT a resource, these two assumptions are in play:

• You are referring to an entity, not to a collection.
• The entity you are supplying is complete (the entire entity).

The PUT includes all of the parameters on the entity, but PATCH only includes the one that was being modified. See the below example, create a user using POST:

POST /users/1

{
    "username": "javapedia",
    "email": "user1@javapedia.net"
}

If you want to modify this entity later, you choose between PUT and PATCH. A PUT might look like this:

PUT /users/1

{
    "username": "javapedia",
    "email": "user123@javapedia.net"    //new email ID
}

The same update using PATCH look like this:

PATCH /users/1

{
    "email": "user123@javapedia.net"    //new email ID
}

When using PUT, it is assumed that you are sending the complete entity, and that the complete entity replaces any existing entity at that URI. In the above example, the PUT and PATCH accomplish the same goal: they both change this user's email address. But PUT handles it by replacing the entire entity, while PATCH only updates the fields that were supplied, leaving the others alone. So PUT is considered idempotent however PATCH is not.

TrustStore is used to store certificates from Certified Authorities (CA) that verify the certificate presented by the server in an SSL connection. While Keystore is used to store private key and identity certificates that a specific program should present to both parties (server or client) for verification.