Publishing a Web Service with 4D

Publication of a Web Service in 4D is generally carried out in three stages:

1. Creation of the method to be published
2. Configuration of the publication (WSDL)
3. Publication

Additional customizing stages can be defined, but they are not mandatory.

You can create any type of project method intended for publication as a Web Service. The method must accept parameters and return a result. It is imperative that these parameters be declared in the method header using commands of the Compiler theme. 

By default, 4D formats the parameters necessary for the operation of methods when published as Web Services. You can, however, modify these parameters using the SOAP DECLARATION command. 

4D automatically takes care of decoding and encoding the data received and sent via SOAP. 

Warning: The names of methods are used as XML tags in SOAP requests. In conformity with the XML standard, these names must not begin with a number nor contain spaces. Moreover, in order to avoid any risk of incompatibility, it is advisable not to use any extended characters (such as accented characters). 

To define and monitor the development of a method published as a Web Service, you must use the commands of the “Web Services” theme — refer to the Web Services (Server) section in the 4D Language Reference manual.

To be able to publish one or more methods of your database as Web Services, the following conditions must be met.

• The machine used as SOAP server (4D single-user application or 4D Server) has a 4D SOAP license.
• The 4D Web server must be launched.
• The Allow Web Services Requests option on the SOAP page in the Database Settings dialog box of the application must be checked. If it is not, 4D refuses SOAP requests and does not generate a WSDL.
  
  When this option is checked, 4D creates the WSDL file (see Generation of the WSDL). 
• Each method to be published must be Offered as a Web Service. This configuration is carried out using an option located in the Method Properties window:
  
  Note: For more information about this window, refer to the Project method properties section.
  When the Offered as a Web Service option is checked, the corresponding method can be called as a Web Service via a SOAP request.
  Note: If the Published in WSDL option is also checked, the method will appear in the WSDL of the server (see the following paragraph).

In the Methods Page of the 4D Explorer, specific icons indicate the methods offered as Web Services and those published in the WSDL file .

The WSDL describes, in XML language, the syntax and information needed for calling the 4D method (Method name, URL, parameters, etc.).

In 4D, the WSDL corresponds to a single Web Service. It defines the methods and their parameters and can be consulted at a specific location. In 4D, the WSDL is not an actual “file” (it only exists in memory and is not written to disk); it is a URL named 4DWSDL for Web Services published in RPC mode or 4DWSDL/DOC for Web Services published in DOC mode. It is always located at the root of the Web server.

For example, if the address of your Web server is http://www.myserver.com, you could consult the WSDL at the following URL:

• http://www.myserver.com/4DWSDL(RPC mode)
• http://www.myserver.com/4DWSDL/DOC (DOC mode)

To add or remove a method in the WSDL, simply check or uncheck the corresponding option in the Method Properties window. 4D will immediately update the WSDL contents. 

Note: In the 4D Explorer, a specific icon distinguishes methods that are published in the WSDL.

When Web Services requests are allowed, 4D automatically and dynamically generates the WSDL of the 4D Web server if at least one method has the Published in WSDL option checked in the Method Properties window. By default, this option is not checked.

Each Web Service published on the Internet has a name. This name is used to differentiate the services both at the SOAP server level (when the server publishes several different Web Services), as well as in the Web Services directories. 

By default, 4D uses the name A_WebService. This parameter can be modified on the "Web services" page of the Web theme in the Database Settings.

Warning: In conformity with the XML standard for tag names, the character strings used must not begin with a number nor contain spaces. Moreover, in order to avoid any risk of incompatibility, it is advisable not to use any extended characters (such as accented characters).

Each Web Service published on the Internet must be unique. The uniqueness of the names of Web Services is ensured using XML namespaces. A namespace is an arbitrary character string used to identify a set of XML tags in a unique way. Usually, the namespace begins with the URL of the company (http://mycompany.com/mynamespace). In this case, it is not indispensable to have anything in particular at the defined URL; what matters is that the character string used is unique.

By default, 4D uses the following namespace: http://www.4d.com/namespace/default. This parameter can be modified on the "Web services" page of the Web theme in the Database Settings.

Any comments associated with methods offered as Web Services and published in the WSDL automatically appear in this file as a “documentation” field.

These comments must be entered on the Methods Page of the Explorer (see the Using comments section).

This mechanism is used to describe or document the published methods. The interpretation and handling of this field will depend on the implementation of the client Web Service.

Once your Web Service has been published by 4D, any client application that supports Web Services can connect to it. The access mode and the processing of the information exchanged with the Web Service server will depend on the client application used for the operation. 

All information needed for the use of a Web Service (such as the URL of the service, the parameters to be used, etc.) are published in the WSDL of 4D. In theory, the use of a Web Service should thus begin with the reading of the WSDL of the SOAP server in order to retrieve this information. In 4D, the URL of the WSDL is http://ServerAddress/4DWSDL (RPC mode ) or http://ServerAddress/4DWSDL/DOC (DOC mode).

However, this step is not mandatory. Connection to the SOAP server can be carried out directly. 

Here is a list of the values needed to establish SOAP requests, as well as their method of definition:

• Access URL to a Web Service published by 4D
  http://ServerAddress/4DSOAP/ (RPC mode) or
  http://ServerAddress/4DSOAP/DOC (DOC mode)
  (not customizable)

• Web Service name
  By default: A_WebService
  Customizable value (see Customizing a Web Service name).

• Name of published method
  Name of the 4D project method defined by the developer (see Creating a Web Service method).

• Method parameters
  The parameters must be declared in the method (defined by the developer).
  Default SOAP names: FourD_arg0, FourD_arg1... FourD_argn
  Customizable names using the SOAP DECLARATION command.

• Namespace
  By default: http://www.4d.com/namespace/default
  Customizable value (see Customizing a namespace).

• Contents of SOAP Action field
  ServiceName#MethodName (not customizable).