netbeans.apache.org/src/content/kb/docs/websvc/intro-ws.adoc - netbeans-website - Git at Google

 //
 //     Licensed to the Apache Software Foundation (ASF) under one
 //     or more contributor license agreements.  See the NOTICE file
 //     distributed with this work for additional information
 //     regarding copyright ownership.  The ASF licenses this file
 //     to you under the Apache License, Version 2.0 (the
 //     "License"); you may not use this file except in compliance
 //     with the License.  You may obtain a copy of the License at
 //
 //       http://www.apache.org/licenses/LICENSE-2.0
 //
 //     Unless required by applicable law or agreed to in writing,
 //     software distributed under the License is distributed on an
 //     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 //     KIND, either express or implied.  See the License for the
 //     specific language governing permissions and limitations
 //     under the License.
 //

 = Introduction to Web Services
 :jbake-type: tutorial
 :jbake-tags: tutorials
 :jbake-status: published
 :icons: font
 :syntax: true
 :source-highlighter: pygments
 :toc: left
 :toc-title:
 :description: Introduction to Web Services - Apache NetBeans
 :keywords: Apache NetBeans, Tutorials, Introduction to Web Services
 :sectlinks:
 :reviewed: 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 link:https://www.openapis.org/[OpenAPI], link:https://www.w3.org/Submission/wadl/[WADL], and link:https://www.w3.org/TR/wsdl20/[WSDL].

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

 * *REST*: **RE**presentational **S**tate **T**ransfer 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 <<rest,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* (**C**reate **R**ead **U**pdate **D**elete) 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 link:https://eclipse-ee4j.github.io/jersey/[+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

 * link:https://eclipse-ee4j.github.io/jaxrs-api/apidocs/3.0.0/[JAX-RS API]
 * link:https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html[Jakarta RESTful Web Services]

 Tools to explore and test REST services:

 * link:https://httpie.io/[httpie] (command line client)
 * link:https://github.com/advanced-rest-client/arc-electron[Arc]
 * link:https://www.postman.com/[Postman]

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

 * xref:rest.adoc[+Getting Started with RESTful Web Services+]
 * xref:zillow.adoc[+SaaS: Zillow+]

 ==  SOAP Web Services

 *SOAP* is a messaging protocol for web services (formerly known as **S**imple **O**bject **A**ccess **P**rotocol). 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* (**W**eb **S**ervices **D**escription **L**anguage) 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

 * link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/[Jakarta XML Web Services]|
 * link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/apidocs[JAX-WS]
 * link:https://eclipse-ee4j.github.io/metro-wsit/[Eclipse Metro]

 Tools to explore and test SOAP services:

 * link:https://www.soapui.org/[SOAPUI]

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

 * xref:jax-ws.adoc[Getting Started with JAX-WS Web Services]
 * xref:client.adoc[Developing JAX-WS Web Service Clients]
 * xref:flower_overview.adoc[Web Service Passing Binary Data] - a separate learning trail about using web services to pass binary data which are displayed in a client using Swing components
 * xref:wsit.adoc[Advanced Web Service Interoperability] (demonstrates WSIT)

 == 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 <<comp>>.

 .Comparison between REST and SOAP
 [source#comp,%header,cols=3*,stripes=even,frame=none, grid=rows]
 |===
 | |SOAP |REST

 |Endpoint |All operations belong to a single URI | Each resource expose with its own URI
 |Interface Description|WSDL|Often as OpenAPI
 |Operations|Defined in interface description|HTTP methods (typically create CRUD interface)
 |Transport Protocol|Different are possible (often HTTP)|HTTP
 |Message Exchange|XML according to SOAP|Different are possible (often JSON)
 |Bandwith Usage|Higher (because of XML)|Less (than SOAP)
 |Security|Built in mechanisms|No mechanisms built in
 |Java Specification|link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/[Jakarta XML Web Services]|link:https://jakarta.ee/zh/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html[Jakarta RESTful Web Services]
 |Java API|link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/apidocs[JAX-WS]|link:https://jakarta.ee/zh/specifications/restful-ws/3.0/apidocs[JAX-RS]
 |Java Reference Implementation|link:https://eclipse-ee4j.github.io/metro-wsit/[Eclipse Metro]|link:https://eclipse-ee4j.github.io/jersey/[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 link:https://docs.github.com/en/developers/overview/about-githubs-apis[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.
	//
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.
	//

	= Introduction to Web Services
	:jbake-type: tutorial
	:jbake-tags: tutorials
	:jbake-status: published
	:icons: font
	:syntax: true
	:source-highlighter: pygments
	:toc: left
	:toc-title:
	:description: Introduction to Web Services - Apache NetBeans
	:keywords: Apache NetBeans, Tutorials, Introduction to Web Services
	:sectlinks:
	:reviewed: 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 link:https://www.openapis.org/[OpenAPI], link:https://www.w3.org/Submission/wadl/[WADL], and link:https://www.w3.org/TR/wsdl20/[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 <<rest,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 link:https://eclipse-ee4j.github.io/jersey/[+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

	* link:https://eclipse-ee4j.github.io/jaxrs-api/apidocs/3.0.0/[JAX-RS API]
	* link:https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html[Jakarta RESTful Web Services]

	Tools to explore and test REST services:

	* link:https://httpie.io/[httpie] (command line client)
	* link:https://github.com/advanced-rest-client/arc-electron[Arc]
	* link:https://www.postman.com/[Postman]

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

	* xref:rest.adoc[+Getting Started with RESTful Web Services+]
	* xref:zillow.adoc[+SaaS: Zillow+]

	== 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

	* link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/[Jakarta XML Web Services]\|
	* link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/apidocs[JAX-WS]
	* link:https://eclipse-ee4j.github.io/metro-wsit/[Eclipse Metro]

	Tools to explore and test SOAP services:

	* link:https://www.soapui.org/[SOAPUI]

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

	* xref:jax-ws.adoc[Getting Started with JAX-WS Web Services]
	* xref:client.adoc[Developing JAX-WS Web Service Clients]
	* xref:flower_overview.adoc[Web Service Passing Binary Data] - a separate learning trail about using web services to pass binary data which are displayed in a client using Swing components
	* xref:wsit.adoc[Advanced Web Service Interoperability] (demonstrates WSIT)

	== 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 <<comp>>.

	.Comparison between REST and SOAP
	[source#comp,%header,cols=3*,stripes=even,frame=none, grid=rows]
	\|===
	\| \|SOAP \|REST

	\|Endpoint \|All operations belong to a single URI \| Each resource expose with its own URI
	\|Interface Description\|WSDL\|Often as OpenAPI
	\|Operations\|Defined in interface description\|HTTP methods (typically create CRUD interface)
	\|Transport Protocol\|Different are possible (often HTTP)\|HTTP
	\|Message Exchange\|XML according to SOAP\|Different are possible (often JSON)
	\|Bandwith Usage\|Higher (because of XML)\|Less (than SOAP)
	\|Security\|Built in mechanisms\|No mechanisms built in
	\|Java Specification\|link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/[Jakarta XML Web Services]\|link:https://jakarta.ee/zh/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html[Jakarta RESTful Web Services]
	\|Java API\|link:https://jakarta.ee/zh/specifications/xml-web-services/3.0/apidocs[JAX-WS]\|link:https://jakarta.ee/zh/specifications/restful-ws/3.0/apidocs[JAX-RS]
	\|Java Reference Implementation\|link:https://eclipse-ee4j.github.io/metro-wsit/[Eclipse Metro]\|link:https://eclipse-ee4j.github.io/jersey/[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 link:https://docs.github.com/en/developers/overview/about-githubs-apis[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.