Introduction to Web Services

Last reviewed on 2021-08-03

This is an introduction to web service concepts and technologies and their support within Apache NetBeans IDE. It is meant to help newcomers to web services before they use any tutorials.

Web services are distributed application components that are externally available (via interface). Externally means that you can access them remotely typically based on common internet protocols (such as HTTP). You can use them to integrate applications that are written in different languages and run-on different platforms. Web services are language and platform independent because vendors have agreed on common web standards.

Hence, there are a lot of frameworks which enable web service development and consumption across all modern programming languages. Because web services are used widely and independent of platforms, there is also a need to standardize interface description. Amongst others, three common approaches to interface description are OpenAPI, WADL, and WSDL.

Several programming models are available to web service developers. These models fall into two major categories, both supported by the IDE:

  • REST: REpresentational State Transfer is the currently the most common way to create web services. In REST, resources have URIs and are manipulated through HTTP methods. For more details, see RESTful Web Services.

  • SOAP: In traditional web service models, web service interfaces are exposed through WSDL documents (a type of XML), which have URLs. Subsequent message exchange is based on the protocol SOAP and according messages. For more details, see SOAP Web Services.

RESTful Web Services

REST-based (or RESTful) web services are collections of web resources. In terms of REST, objects are understood as resources that are uniquely identified via an URI (Unified Resource Identifier) and represented in different formats (such as text, image, audio, video, application). Communication is established via HTTP methods (most common are GET, POST, PUT, DELETE). By implementing these common HTTP methods a CRUD (Create Read Update Delete) interface is created by the RESTful service. Therefore, no further protocol layer, such as SOAP, is necessary. For communication messages different formats can be used. A quite common choice is JSON (JavaScript Object Notation).

In the context of web services, this means that a component which implements a web service that uses a REST binding (a so-called RESTful web service) is to be understood as follows:

  • An object/data set is hidden behind the endpoint URI.

  • The object can be processed programmatically by the typical HTTP verbs (GET, POST, …​)

  • The messages (request and response) can be defined in any format, often JSON is used.

REST services are the most common web service type. Almost all large companies and projects provide REST APIs, such as Flickr, Google Maps and Amazon. Apache NetBeans IDE Software as a Service (SaaS) functionality lets you use Facebook, Zillow, and other third-party-provided services in your own applications.

Jakarta RESTful Web Services

Jakarta RESTful Web Services is part of Jakarta EE specifications and provides descriptions and APIs to develop RESTful web services as well as clients. Jakarta RESTful Web Services provide an annotation-based API to expose Java POJOs as RESTful web services. The corresponding implementation and APIs are called JAX-RS. Following web service standards, clients implemented by means of JAX-RSare not restricted to services implemented using JAX-RS.

The open source reference implementation for building RESTful web services in Java is Project Jersey . The Jersey APIs are available as the "RESTful Web Services" plugin for Apache NetBeans IDE. This plugin will also be activated once you create your first Jakarta EE project.

Further Reading & Resources

Specifications and API documentation

Tools to explore and test REST services:

The following knowledge base tutorials involve creating and consuming REST services:

SOAP Web Services

SOAP is a messaging protocol for web services (formerly known as Simple Object Access Protocol). Nowadays SOAP also serves as a synonym for web services that rely on SOAP. SOAP incorporates and relies on a lot of so called WS* standards. SOAP itself includes definitions for calls of remote services (methods), message exchange and message structures (especially their packaging, called envelope and their encoding). SOAP relies a lot on XML, hence definitions and messages are typically created as XML documents.

The interface description of a SOAP web service is also provided in XML, by a so called WSDL (Web Services Description Language) document. WSDL is actually a standard of its own. The creation of SOAP web services can follow contract first or code first principles. In a contract first scenario a WSDL document is used to generate service stubs. In a code first scenario a component is declared to expose a SOAP web service and a WSDL document is generated from this declaration.

The WSDL is exposed on the net to make the service accessable. Parties interested in using the web service can create a client based on the WSDL. The WSDL file also defines possible operations for a given service endpoint and hence, the range of operations to a single endpoint (URI) can be much broader than what is available in REST (HTTP methods). Also SOAP services may use transport protocols other than HTTP.

Jakarta XML Web Services

Jakarta XML Web Services is part of Jakarta EE specifications and provides descriptions and APIs (JAX-WS) to develop and consume SOAP web services. There are utilities to generate WSDL (wsgen) from source code or create Java code (wsimport) from a WSDL file. Until Java 10 this was part of Java SE, with Java 11 these tools have been removed from JDK and are now available as dependency and can of course directly be used within Apache NetBeans.

JAX-WS is built on the earlier JAX-RPC model but uses specific Jakarta EE features, such as annotations, to simplify the task of developing web services. Because it uses SOAP for messaging, JAX-WS is transport neutral. It also supports a wide range of modular WS-* specifications, such as WS-Security and WS-ReliableMessaging. When you create a web service client, you have the option of using either the JAX-WS or JAX-RPC model. This is because some older JAX-RPC services use a binding style that is not supported by JAX-WS. These services can only be consumed by JAX-RPC clients.

Further Reading & Resources

Specifications and API documentation

Tools to explore and test SOAP services:

The following knowledge base tutorials involve creating and consuming JAX-WS SOAP-based web services:

Conclusion & Comparison

Currently, most services are implemented following the REST paradigm. SOAP is still being in use. While SOAP can be convenient in terms of development, it also has some burden, primarily in terms of performance and in standardized (CRUD) interfaces. A comparison between concepts in SOAP and REST is shown in Comparison between REST and SOAP.

Table 1. Comparison between REST and SOAP


All operations belong to a single URI

Each resource expose with its own URI

Interface Description


Often as OpenAPI


Defined in interface description

HTTP methods (typically create CRUD interface)

Transport Protocol

Different are possible (often HTTP)


Message Exchange

XML according to SOAP

Different are possible (often JSON)

Bandwith Usage

Higher (because of XML)

Less (than SOAP)


Built in mechanisms

No mechanisms built in

Java Specification

Jakarta XML Web Services

Jakarta RESTful Web Services

Java API



Java Reference Implementation

Eclipse Metro

Eclipse Jersey

Also there is another paradigm called GraphQL, it was introduced by Facebook in 2012, made open source in 2015 and is currently maintained by the GraphQL Foundation. GraphQL is said to be a query language for APIs. Similar to REST, there are discussions about whether GraphQL is a web services approach.

GraphQL is becoming increasingly popular and well-known APIs are now also offered via GraphQL (for example, the GitHub API is now available not only as a REST API, but also as a GraphQL API). It remains to be seen whether GraphQL will replace REST in the future. Although there are Java libraries that enable GraphQL, there is currently no Java standard for GraphQL.