3DEXPERIENCE Web Services Guide
3DEXPERIENCE Platform comprises various applications and services. It also has platform administration control centers to Manage members, role-based access, usage analytics and application behavior configuration.
3DEXPERIENCE Platform Apps
- 3DPassport – Identity management and authentication across all apps.
- 3DSpace – Manage and share data, documents, related information.
- 3DPlay – Visualize and Review 3D designs in the real-time
- 3DDashboard – Aggregate all information that matters in personalized Dashboard
- 3DSearch & 6WTags – Search and Discover content. Add Semantics by Tagging the content 6 dimensions (Who-What-When-How-Where- Why)
- 3DCompass – Discover 3DEXPERIENCE Worlds, access to roles and apps in one click
- 3DSwym – Leverage communities to share expertise, knowledge skills & conversations
- 3DMessaging – Connect instantly in context and share designs, collaborate through chat
- 3DComment – Share your thoughts & POV. Engage in discussion with peers.
- 3DDrive – Secure file storage on the cloud with 3DPassport.
- 3DNotification – Stay Informed about events you subscribe to
3DEXPERIENCE Platform Application Interaction
- 3DEXPERIENCE platform services interact with each other, and also with external services, via https protocol for security reasons.
- In order for the application to be contacted by its clients, Reverse Proxy should be cascaded between the client and the application server for the service.
Web-Service – Introduction
- A Web-Service is any standard Application that is available over the network (Internet) which is capable of interacting with other Applications over the same network.
- In simple terms, a Web-Service is an application that responds to a call made by another application over the network.
- As a response, the Web-Service can:
- Perform a task. For example, create some new data in the Database
- Send back a response to the calling application, in a standard exchange format. The response format can be in XML, JSON, etc.
- Web-Services are typically designed to allow interoperability. This means that:
- Web- Services are operating system independent.
- The calling and responding applications may be hosted in environments with different operating systems.
- Web-Services are programming language independent.
- The calling application doesn’t need to know about the programming language that was used to write the web -service. It should only be able to process the response.
- Web- Services are operating system independent.
- To summarize, a Web-Service is any application that:
- Is available over the Internet or a private network
- Uses a standard messaging system, like XML or JSON
- Is not tied to any particular Operating System or programming language
Web-Service – Characteristics
- In a standard Web-Service, the following hold true:
- Standard protocols like HTTP are used for request and responses between Client machine and Server machine
- Standard data exchange formats, like XML or JSON, are used to transfer data between Client machine and Server machine
- In practice, a Web-Service commonly provides an object-oriented Web-based interface to a database server.
- The Web-Service may be utilized, for example, by another Web server, or by a mobile app, that provides a user interface to the end-user.
- Web-Services are designed to be programming language independent:
- The client application does not need to know about programming language that was used to develop the Web-Service
- For example, using Web-Services, a Java application can interact with other Java, .Net or PHP applications
- The State of a Web-Service is one of the most commonly used terms. The State of a Web-Service can be confusing to understand:
- A Web-Service, depending on its nature and architecture, can be either Stateless or Stateful.
- A Stateful web-service is one that maintains some information between two consecutive requests from client to server.
- Example: Let’s say that an User enters username and password while invoking a web-service. A Stateful web-service may retain the username and password for the next call, so that the User does not have to enter it again.
- A Stateless web-service is one that does not maintain any information between two consecutive requests from client to server.
- Example: For calling a Stateless web-service, the username and password would need to be passed along with the request every time. The application would not store it anywhere.
- An application built on Stateful web-services generally tends to be more wasteful of resources, as compared to a Stateless web-service.
- This is because the application has to maintain the state of all open connections with its clients. More the number of clients that are connected to the application at the same time, more resources are spent to maintain the states of the open connections.
- Application developers generally prefer to use Stateless web-services in their applications as they are lightweight and less taxing on the application servers.
Web-Service – Points to Remember
- Web-Services are not to be confused with Java Servlets.
- A servlet is a Java programming language class that is used to extend the capabilities of servers and create web applications that responds to incoming requests.
- Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers.
- The generic differences between Web-Services and Servlets are as follows:
|A Web-Service is a broader umbrella term, which may implement a servlet to deliver the service||A Servlet is a Java specific approach to that allows a Java application to respond to incoming requests|
|A Web-Service may use any open standard protocol, like HTTP or SOAP||A Servlet can operate only over HTTP protocol for exchanging data|
|Web-Services offer service discovery mechanisms like WSDL, WADL, etc. They provide a comprehensive list of available services, data exchanged in request and response, etc.||In case of a Servlet, the caller does not know what parameters are accepted by the Servlet application. The caller can only open an URL connection and pass parameters to the Servlet as part of the URL, without any knowledge of whether the parameters are actually being processed or if some parameters are missing.|
Types of Web-Services
- Mainly, there are two types of Web-Services:
- SOAP Web-Services
- RESTful Web-Services
- In recent times, there has been much discussion about the GraphQL libraries which offer certain advantages over REST Web-Services.
- However, GraphQL is still not as standardized as REST or SOAP Web-Services. We are not going to discuss GraphQL in this article.
SOAP – Introduction
- SOAP stands for Simple Object Access Protocol.
- SOAP is a W3C recommendation for communication between two applications.
- SOAP was developed as an intermediate language so that applications built on various programming languages could communicate easily with each other and avoid the extreme development effort.
- SOAP is an XML-based protocol for accessing Web-Services over HTTP.
- Some legacy systems communicate over Simple Mail Transfer Protocol (SMTP) using SOAP.
- HTTP has gained wider acceptance as it works well with today’s internet infrastructure. Specifically, HTTP works well with network firewalls.
- SOAP may also be used over HTTPS (which is the same protocol as HTTP at the application level, but uses an encrypted transport protocol underneath) with either simple or mutual authentication.
- Use of XML as the exchange format allows the applications to send complex sets of data. Also, XML is a very standard data exchange format, which can be parsed by any programming language
- A SOAP web-service can be both Stateful and Stateless.
The SOAP Message, or the data-packet that is transferred over the web-service, is an XML document which consists of the following components:
|Envelope||Identifies the XML document as a SOAP message.||Yes|
|Header||Contains header information.||No|
|Body||Contains call and response information.||Yes|
|Fault||Provides information about errors that occurred while processing the message.||No|
Rules applicable for a SOAP message
- Every SOAP message needs to have a root Envelope element. It is absolutely mandatory.
- Every Envelope element needs to have at least one SOAP Body element.
- There can be only one Header tag, or none at all. The Header must appear as the first child of the Envelope, before the Body element.
- A SOAP message must NOT contain a DTD reference
- A SOAP message must NOT contain XML Processing Instructions
- The Envelope changes when SOAP versions change.
- A v1.1 -compliant SOAP processor generates a Fault upon receiving a message containing the v1.2 Envelope namespace.
- A v1.2 -compliant SOAP processor generates a Version Mismatch fault if it receives a message that does not include the v1.2 envelope namespace.
- The option Fault element, if present, must appear as a child element of the Body element.
- A Fault element can only appear once in a SOAP message.
RESTful Web-Service – Introduction
- RESTful Web-Services is a lightweight, maintainable and scalable service that is built using the REST architecture.
- REST Web-Services allow the application to expose their APIs in a secure and stateless manner.
- REST stands for REpresentational State Transfer.
- Some key characteristics of a RESTful service are as follows:
- REST Web-Services operate over the HTTP protocol, using any of the normal HTTP verbs like GET, PUT, POST, DELETE, etc.
- For a REST Web-Service, every component is a resource that is accessed by a common Interface using HTTP standard methods.
- REST Web-Services can work with all standard resources that are supported over HTTP, like text, JSON, XML, etc.
- JSON is the most popular and widely using exchange format in case of REST Web-Services
- Since a REST Web-Service is stateless, it is the entire client’s responsibility to maintain session information, username and password (the application/server does not maintain it).
- To overcome the shortcomings of a stateless web-service, the concept of a cache is often used to store information that is frequently requested for.
- This also helps to reduce network traffic.
- Because of its lightweight, flexible and easy-to-develop nature, and also because of the advantages of being Stateless, REST web-services are gaining popularity over SOAP web-services.
- A REST web-service makes use of HTTP protocol for transferring message between Server and Client.
- Hence, a REST message is exactly the same as an HTTP message. An HTTP message has two categories:
- HTTP Request: An HTTP request has five major components:
- Verb − Indicates the HTTP methods such as GET, POST, DELETE, PUT, etc.
- URI − Uniform Resource Identifier (URI) to identify the resource on the server.
- HTTP Version − Indicates the HTTP version. For example, HTTP v1.1.
- Request Header − Contains metadata for the HTTP Request message as key-value pairs. For example, client (or browser) type, format supported by the client, format of the message body, cache settings, etc.
- Request Body − Message content or Resource representation.
- HTTP Request: An HTTP request has five major components:
- HTTP Response: An HTTP Response has four major components:
- Status/Response Code − Indicates the Server status for the requested resource. For example, 404 means resource not found and 200 means response is ok.
- HTTP Version − Indicates the HTTP version. For example HTTP v1.1.
- Response Header − Contains metadata for the HTTP Response message as
- key-value pairs. For example, content length, content type, response date,
- server type, etc.
- Response Body − Response message content or Resource representation.
Differences between SOAP & REST
Following are the differences between REST and SOAP web-services:
|SOAP is a protocol.||REST is an architectural style.|
|SOAP cannot use REST, because SOAP is a protocol.||REST can use SOAP web-services because it is a concept and can use any protocol like HTTP, SOAP.|
|SOAP uses services interfaces (WSDL) to expose the business logic.||REST uses URI to expose business logic.|
|JAX-WS is the java API for SOAP web-services.||JAX-RS is the java API for RESTful web-services.|
|SOAP defines standards to be strictly followed.||REST does not define too much standards like SOAP.|
|SOAP requires more bandwidth and resources, as its message contains a lot of information in the form of tags.||REST requires less bandwidth and resources, as REST messages mostly consist of JSON data.|
|SOAP defines its own security.||RESTful web-services inherits security measures from the underlying transport layer.|
|SOAP permits XML data format only.||REST permits different data format such as Plain-text, HTML, XML, JSON etc.|
Technologies used to Develop Web-Services
Universal Description, Discovery and Integration (UDDI)
- An organization can develop a Web-Service, but it will not be of use if the Users cannot find it, or if the Users do not know of its existence.
- Universal Description, Discovery and Integration (UDDI) is a platform independent protocol that includes an XML-based registry, by which businesses worldwide can list themselves on the Internet.
- The UDDI also has mechanisms to register new services, and also to locate existing services
- Customers can look up the UDDI to search for services provided by the registered companies.
- The UDDI registry acts as the service-broker
- The below diagram describes the working architecture of a SOAP Web-Service over the internet.
- The displayed architecture can be summarized as follows:
- When a service provider wants to make its services available to service
- consumers, they would first describe the service in a WSDL document.
- The service provider would then register the WSDL in a UDDI Registry.
- The UDDI Registry would then maintain pointers to the WSDL document and
- to the Web-Service
- When a Service Consumer wants to use a service, they would lookup the
- UDDI registry to find services matching their requirements.
- The UDDI then returns the WSDL description of the web-service, as well as the access point of the service.
- The Service Consumer then uses the WSDL to construct a SOAP Message, which is then used to communicate with the actual webservice.
Web Services Description Language (WSDL)
- Web Services Description Language (WSDL) is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.
- The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint.
- In simple words, a WSDL document is an XML-based file that tells the client (Web-Service Consumer) about the following:
- Purpose of the Web-Service
- The exposed functionalities (methods)
- How to call the Web-Service (expected inputs)
- Expected output
- The structure of a WSDL document is as shown in below diagram.
- If the URL of the Web-Service is http://example.org:8080 then the WSDL file can be seen by the following URL call: http://example.org:8080?wsdl
- Web Interface Definition Language (WIDL) was one of the pioneering specifications for description of remote Web-Services. It was based on an XML format, much similar to WSDL, and was suited to users of remote procedural technologies, such as RPC and CORBA. It, however, lost its significance with the rise of message-based XML technologies
WSDL – Tags Used
- Below are the descriptions of the most important tags in a WSDL file:
- <definitions>: Encloses the entire WSDL definition into one unit. All other tags are placed within the definitions tag.
- <types>: This tag is used to define complex datatypes, which will be used in the messages exchanged between the client application and the web-service.
- It is to be noted that:
- WSDL is not tied exclusively to a specific typing system
- If the service uses only XML Schema built-in simple types, such as strings and integers, then types element is not required.
- <message>: This tag is used to define the message which is exchanged between the client application and the web server. These
- messages will explain the input and output operations which can be performed by the web-service.
- <portType>: This tag is used to encapsulate every input and output message into one logical operation.
- <binding>: This tag is used to bind the operation to the particular port type. This tag defines the protocol and data format for each type.
- <service>: This tag is a name given to the Web-Service itself. Here, we define the URL that will be called upon invoking the Web-Service.
Web Application Description Language
- WADL is an acronym for Web Application Description Language.
- WADL is an XML document which describes Web-Services that work over the HTTP protocol.
- WADL is considered as the REST equivalent to SOAP’s WSDL.
- WADL is lightweight, easier to understand, and easier to write as compared to WSDL.
- WADL was championed by Sun Microsystems.
- In some aspects, WADL is not as flexible as WSDL (no binding for SMTP servers), but it is sufficient for any REST service and is much less verbose.
- Some key aspects of WADL are as follows:
- WADL is intended to simplify the reuse of web-services that are based on the existing HTTP architecture of the Web.
- The service described using a set of resource elements
- Each resource contains param elements to describe the inputs, and method elements which describe the request and response of a resource.
- Use of WADL is not considered standard.
- REST Web-Services do not actually need any separate WADL definition. They may use URIs to allow discovery of their resources.
Web-Service Discovery in 3DEXPERIENCE Platform
- Although the 3DEXPERIENCE platform no longer supports SOAP web-services, WSDL or WIDL documents for pre-existing legacy services can be found at the following location in the 3DSpace deployment directory:
- <TomEE Deployment Root>\WEB-INF\resources\widl
- <TomEE Deployment Root>\WEB-INF\resources\wsdl
- It is very important to note that SOAP Web-Services are no longer supported in the 3DEXPERIENCE platform
- New web-services developed using SOAP protocol will not be guaranteed by DS
- Only REST web-services are now supported in the 3DEXPERIENCE platform. REST web-services are discovered using their URI.
- The URI of a JAX-RS web-service is configured by the use of @ApplicationPath and @Path annotations.
HTTP Methods for Web-Services
HTTP Methods – Introduction
- Hyper Text Transfer Protocol (HTTP) works as a request-response protocol between a client and a server.
- In order to exchange data, HTTP makes use of Methods or Verbs. Some of the most widely used HTTP methods are listed below
|GET||The GET method is used to retrieve information from the given server using a given URI.|
|POST||A POST request is used to send data to the server, for example, customer information, file upload, etc. using HTML forms.|
|HEAD||Same as GET, but transfers the status line and header section only. The response doesn’t have a body.|
|PUT||PUT is used to send data to a server to create or update/replace a resource|
|PATCH||PATCH verb is used to update or modify an existing resource|
|DELETE||Removes all current representations of the target resource given by a URI|
|CONNECT||Establishes a tunnel to the server identified by a given URI|
|OPTIONS||Describes the communication options for the target resource|
|TRACE||Performs a message loop-back test along the path to the target resource|
Although the PUT and PATCH verbs may look similar, they have their differences.
- The PUT method uses the request URI to supply a modified version of the requested resource which replaces the original version of the resource
- The PATCH method supplies a set of instructions to modify the existing resource. It does not replace the existing resource. The PATCH request only needs to contain the changes to the resource, not the complete resource.
HTTP Methods – Example
- GET Method: In a GET request, the data is primarily transferred as URL parameters (name/value pairs).
- Example: GET /test/demo_form.php?name1=value1&name2=value2 HTTP/1.1
- POST Method: The data sent to the server with POST is stored in the request body of the HTTP request.
- POST /test/demo_form.php HTTP/1.1
- Host: example.com
HTTP Methods – GET vs POST
The following table compares the two HTTP methods: GET and POST
|BACK button/Reload||Harmless||Data will be re-submitted (the browser should alert the user that the data are about to be re-submitted)|
|Bookmarked||Can be bookmarked||Cannot be bookmarked|
|Cached||Can be cached||Not cached|
|Encoding type||application/x-www-form-urlencoded||application/x-www-form-urlencoded or multipart/formdata. Use multipart encoding for binary data|
|History||Parameters remain in browser history||Parameters are not saved in browser history|
|Restrictions on data length||Yes, when sending data, the GET method adds the data to the URL; and the length of a URL is limited (maximum URL length is 2048 characters)||No restrictions|
|Restrictions on data type||Only ASCII characters allowed||No restrictions. Binary data is also allowed|
|Security||GET is less secure compared to POST because data sent is part of the URL Never use GET when sending passwords or other sensitive information!||POST is a little safer than GET because the parameters are not stored in browser history or in web server logs|
|Visibility||Data is visible to everyone in the URL||Data is not displayed in the URL|
3DEXPERIENCE Platform Web-Service Development
Comparison Table on the available technologies
|Type of service||Doc-based||SOAP/Doc-based||REST||SOAP/Doc-based|
|Standard based||Proprietary||AXIS 1.4 *Obsolete since about 2008||Java EE 6 Web Profile||Java EE 6 Web Profile|
|Customizable||R&D Only **Requires ADELE compiler||No||Yes||No|
|Object visibility||IRPC only||ER only||ER only (R2015x/R2016x) IRPC/ER (>R2016x)||ER only|
|Hot Deploy||No||Yes||No||Not without heavy customization|
|Availability||Being phased out||Being phased out||Limited public endpoints||No plan|
JAX-RS API – Introduction
- JAX-RS is a JAVA based programming language API and specification to provide support for creating RESTful Web-Services.
- JAX-RS uses annotations available from Java SE 5 to simplify the development of web-services and its subsequent deployment.
- From version 1.1 on, JAX-RS is an official part of Java EE 6. A notable feature of being an official part of Java EE is that no configuration is
- necessary to start using JAX-RS.
- For environments with releases earlier than Java EE 6, a small entry in web.xml deployment descriptor file is required to deploy the Web-Service
- JAX-RS also provides support for creating clients for RESTful Web-Services.
JAX-RS API – Annotations
Annotation Description – Table
|@ApplicationPath||Identifies the application path that serves as the base URI for all resources. This annotation is applied only to a subclass of javax.ws.rs.core.Application|
|@Path||Identifies the Relative path of resource class/method relative to @ApplicationPath|
|@PathParam||Binds the parameters passed to a method to values in the Path.|
|@QueryParam||Binds the parameters passed to a method to values in the request URL parameter|
|@Consumes||Specifies the MIME types of the HTTP request that the resource can consume|
|@Produces||Specifies the MIME types of the HTTP response that the web-service returns back to the client|
|@FormParam||Binds the parameter passed to the method to a form value|
|@GET||Designates a method for the HTTP GET request|
|@POST||Designates a method for the HTTP POST request|
|@PUT||Designates a method for the HTTP PUT request|
|@DELETE||Designates a method for the HTTP DELETE request|
|@HEAD||Designates a method for the HTTP HEAD request|
|@OPTIONS||Designates a method for the HTTP OPTIONS request|
|@HeaderParam||Represents the parameters of the header|
|@CookieParam||Represents the parameters of the cookie|
|@Context||Used to inject information like Security Context into an instance field or directly into the resource method as a parameter|
Implementing REST Web-Service in 3DSpace
- The architecture of a 3DEXPERIENCE platform web-service can be explained with the following diagram.
- The main Application class ( CustoModeler), which would act as the entry point into the application, needs to conform to the following rules:
- It applies the @ApplicationPath annotation
- It extends the ModelerBase class
- The ModelerBase class extends the javax.ws.rs.core.Application which is needed for the @ApplicationPath annotation.
- The ModelerBase class contains the following important
- init(): Used by the servlet container to initialize the internal servlet implementation.
- getServices(): This is an abstract method which is overridden in the main Application class to return the class(es) implementing the resources.
- By overriding the getServices() method, the main Application class returns the service class(es) to the servlet container.
- In the example in the previous page, the Service class is named as MyService.
- Below are some important points that are to be noted regarding the service class( es):
- The service class applies the @Path annotation either at the class level or the method level
- The service class extends the RestService
- The class RestService implements the method getAuthenticatedContext() which is required to obtain a valid Matrix context that is needed for transactions.
- The service class applies annotations like @GET, @POST, etc., as required, against corresponding methods to designate resources for the HTTP request verbs that the service is supposed to respond to.
Web Services capability is the strategic direction going forward to address customized requirements on the 3DEXPERIENCE Platform. Learn 3DEXPERIENCE from PLM Coach, and stay up to date with the evolving technology, grab and monetize potential opportunities.
🌍 For PLM / CAD Training Visit ► https://plmcoach.com
Follow PLM Coach on Social Media:
📧 Contact PLM Coach:
Follow the link to Training Inquiry Form to provide your details
Follow the link to Text PLM Coach on WhatsApp
☏ Mobile Number ► +91-7989703878
💌 Email ► firstname.lastname@example.org