ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Communication / Web services
  • Overview
  • Principle for calling a function of a REST Webservice
  • Creating a REST Webservice
  • Steps to follow
  • Step 1: Creating a project or project configuration whose type is REST Webservice
  • Step 2: Creating a description of REST Webservice
  • Step 3: Creating entry points
  • Step 3: Method 1: Manual creation of entry points
  • Composition of resource (or URL section)
  • Managing response codes in the code of procedures
  • Step 3: Method 2: Automatic creation of entry points and procedures (methods) for a file found in the analysis
  • Testing a REST Webservice and debugging it
  • Test tool of Webservice: WDTestRest
  • Generating the REST Webservice
  • Deploying a REST Webservice
  • Deploying a Webservice
  • Special case: Deploying a Webservice and running its test on the local computer
  • Calling a REST function through programming
  • For example
  • Generating the OpenAPI definition
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Overview
A REST Webservice is a program hosted on a server containing functions accessible via HTTP requests. Each function (also called API or entry point) corresponds to a process run on the server.
Each entry point is characterized by:
  • a resource,
  • an HTTP method (GET, POST, PUT, ...).
A REST Webservice can contain entry points with identical URLs and different HTTP methods (representing a different action).
The available HTTP methods are as follows:
  • GET to get information.
  • POST to create.
  • PUT to modify.
  • DELETE to delete.
  • PATCH to modify.
  • HEAD to get information.

Principle for calling a function of a REST Webservice

The call to a function of a REST Webservice is performed via a resource (URL).
This resource itself represents the nature of information used as well as their identification. The HTTP methods (verbs) used in the address are used to specify the kind of action to perform.
In the function, the HTTP codes (2xx, 3xx, 4xx and 5xx) are used to indicate the status report of REST function.
For example, the following address:
http://server/Customers/10/Orders
represents the following action: "Retrieve the list of orders for customer #10".
In this address:
  • server represents the address of server hosting the REST Webservice.
  • Customers indicates that data about customers is used.
  • 10 represents the identifier of customer to use.
  • Orders indicates that data about orders is used.
This HTTP request is performed via the GET method which means that data must be retrieved in return.
Creating a REST Webservice

Steps to follow

To create a REST Webservice:
  1. Create a project or project configuration whose type is REST Webservice.
  2. Create one or more descriptions of REST Webservice. A description of REST Webservice is used to group a list of functions for the same theme.
  3. In each description, create the necessary entry points. Two methods can be used to create the entry points: Reminder: An entry point is made of:
    • a procedure or a WLanguage method.
    • an HTTP method.
    • a resource (URL section).
    • the request format and the response format.
  4. The Webservice can be generated and deployed.

Step 1: Creating a project or project configuration whose type is REST Webservice

To create a REST Webservice project:
  1. Create a new project:
    • Display the home page if necessary (Ctrl + <).
    • Click "Create a project".
  2. In the project creation wizard:
    • Select a "SOAP or REST Webservice" project.
    • Choose to generate a REST Webservice.
  3. Finish the wizard.
To create a REST Webservice project configuration:
  1. On the "Project" tab, in the "Project configuration" group, expand "New configuration" and select "Webservice".
  2. In the project configuration generation wizard, choose to generate a REST Webservice.
  3. Finish the wizard.

Step 2: Creating a description of REST Webservice

Reminder: A description of REST Webservice is used to group a list of functions for the same theme.
To create a description of REST Webservice.
  1. In the "Project explorer" pane, select "Descriptions of REST Webservices" then select "New description of REST Webservice" in the context menu (right mouse click).
    Creating a Webservice description
  2. Type the name of the REST Webservice description and validate.
  3. The entry point creation wizard automatically opens.

Step 3: Creating entry points

The REST Webservice entry point creation wizard opens:
  • when creating a new description of REST Webservices.
  • in the "REST Webservice" pane, in the "Entry points" group, by clicking "New".

    Remark: The "REST Webservice" pane is available only when a description of REST Webservice is displayed in the editor.
If the project is associated with an analysis, the entry point creation wizard proposes to select the method for creating entry points:

Step 3: Method 1: Manual creation of entry points

In the rest of the wizard:
  1. Specify the global WLanguage procedure associated with the entry point. This procedure can be created or it can be selected among the existing global procedures.
    Choosing the procedure
  2. Go to the next step.
  3. Choose the HTTP method representing the action to perform (GET, PUT, ...).
    Choosing the HTTP method
  4. Go to the next step.
  5. Define the resource (or URL section) corresponding to the entry point. This resource can include static elements or variable elements (parameters).
    Resource of entry point
    For more details, see Composition of resource.
  6. Go to the next step.
  7. Define the request format and the response format. The standard in REST is JSON but other formats are available.
    • The request format indicates how the data passed during the REST call is formatted.
      Request format
      This format can be as follows:
      • HTML form,
      • JSON,
      • XML,
      • Text (MIME "Text/Plain" type),
      • Binary (for images for example),
      • Variable (the format is free and it must be specified through programming with WebserviceReadMIMEType).
    • For a POST, PUT or PATCH action, you have the ability to automatically deserialize the data passed in query parameter in a parameter of the procedure associated with the entry point:
      Deserialization
      • Check "Deserialize the content automatically...".
        Caution: if the procedure has no defined parameter, the check box "Deserialize the content automatically..." is not enabled.
      • Select the name of target parameter in the list.
        Caution: You must modify the code of the procedure to define the parameter and go back to the entry point creation wizard. It is essential and mandatory to typecast the procedure parameter. The following types of parameters are allowed in the procedure: buffer, Ansi string, structure, array, object. The simple types (integer, date, time, boolean, ...) are not allowed.
        For more details, see REST WebServices: Automatic deserialization of request.
    • The response format indicates how the data retrieved in from a REST call is formatted.
      Request format
      This format can be as follows:
      • None,
      • JSON,
      • XML,
      • Text (MIME "Text/Plain" type),
      • Binary (for images for example),
      • Variable (the format is free and it must be specified through programming with WebserviceWriteMIMEType).
  8. Go to the next step.
  9. Type the description of entry point (free text).
  10. Validate.
The description of different entry points is displayed in the editor.
Request format

Composition of resource (or URL section)

The resource is made of:
  • static elements.
  • variables elements.
  • common parameters (optional).
The static elements represent the objects used. For example, "/Customers" to handle customers.
In the resource creation wizard, a static element corresponds to a "Fixed component".
The variable elements identify the resources used (a customer number, an order number, ...). For example "/Customers/{CustNum}" is used to indicate the customer used via his customer number.
  • In the URL creation wizard, a variable element corresponds to:
    • a variable component whose type is procedure parameter. This component is automatically retrieved in the parameters of associated WLanguage procedure.
    • a variable component whose type is programming, retrieved through programming with WebserviceParameter.
  • A variable element is represented by the following syntax: "{Name variable component}".
    For example, "/Customers/10" is used to handle the customers whose identifier is set to 10.
  • It is quite common to pass the variables elements in the URL during a call to a REST function.
  • In the resource (URL) of entry point, each variable component of programming type corresponds to a parameter passed to the WLanguage procedure associated with the entry point.
  • A variable element is represented by a name when defining the address of the entry point in the editor. For a variable component of programming type, this name must be identical to the parameter name in the WLanguage procedure associated with the entry point.
    At runtime, the value passed in the resource (URL) will be retrieved and placed in the variable. This name is case sensitive. Therefore, it is very important to use the same name in the procedure and in the resource (or conversely) otherwise a runtime error occurs.
You have the ability to combine several static elements and several variable elements. For example:
  • "/Customers/{CustomerID}/Invoices" to retrieve the invoices of a customer identified by his CustomerID.
  • "/Suppliers/{SupID}/Products/{ProdRef}" to retrieve the product identified by "ProdRef" for the supplier identified by "SupID".
The Common parameters section allows you to get:
  • a resource section identical to all entry points. Therefore, there is no need to systematically copy this resource section into each entry point. The modification is performed at a single location.
  • a Prologue procedure that is called before running the function associated with the Webservice entry point (for more details, see Prologue procedure). This type of procedure can, for example, allow an authentication token to be checked during the call to each entry point. The Prologue procedure is a procedure without parameters. This procedure must return:
    • True to continue and run the procedure associated with the entry point.
    • False to stop the call and to avoid running the procedure associated with the entry point. In this case, you must use WebserviceWriteHTTPCode to specify the response status code (4XX or 5XX).
Tip: The definition of common parameters can be used to manage different versions of REST Webservice. For example, a common parameter named "V1" can be used. When creating another version of the web service, simply change "V1" to "V2" to change the resource (URL) of all entry points.
To change the common parameters, go to the "REST webservice" tab, "Options" group, and select "Description".

Managing response codes in the code of procedures

The code of the WLanguage procedures used for the REST Webservices must manage status reports indicating whether the function was properly run or not.
By convention, in a REST Webservice, the execution status reports are returned by using the HTTP response codes. HTTP response codes are classified into families:
  • 2xx codes correspond to successful actions.
  • 3xx codes correspond to redirection errors.
  • 4xx codes correspond to client errors (incorrect HTTP method, incorrect data format sent, etc.).
  • 5xx codes correspond to server errors (WLanguage procedure internal error, etc.)
The response code is returned by WebserviceWriteHTTPCode.
Examples of response codes used:
  • Ask to create a customer via the HTTP POST method. This request was succesful: the code 201 will be returned.
  • Ask to delete a customer via the DELETE method. This request failed because an integrity error was returned by the database: the code 500 will be returned as well as an explanation message.
  • Ask to find a product by passing a reference as parameter via the GET method. This request was succesful: the code 200 will be returned.
  • Ask to find a product by passing a reference as parameter via the GET method. This request failed because the reference does not exist: the code 404 will be returned.

Step 3: Method 2: Automatic creation of entry points and procedures (methods) for a file found in the analysis

In the rest of the entry point creation wizard:
  1. Select the analysis file onto which the entry points will be described.
  2. Go to the next step.
  3. Select the items that will be exposed in the Webservice.
    This items will be accessible in read mode and/or in write mode via the entry points of REST Webservice.
  4. Go to the next step.
  5. Select the key that will be used to access a file record to read it, modify it or delete it.
  6. Go to the next step.
  7. Select the format used to exchange data when calling the entry points of the REST Webservice. 3 formats are available:
    • JSON (UTF-8): The data sent or returned is in JSON format.
    • JSON (UTF-8) (via HRecordToJSON): The data is formatted in an intermediate object created by HRecordToJSON.
    • XML: The data sent or returned is in XML format.
  8. Go to the next step.
  9. Select the list of entry points that will be generated when creating the REST Webservice.
    By default, all types of entry points are generated:
    • Create: Add a record into the data file.
    • Read: Find and read a record in the data file.
    • Update: Update a record in the data file.
    • Delete: Delete a record from the data file.
    • Read all records: Read all records in the data file.
  10. Go to the next step.
  11. It's done. The wizard generates the source code in object (OOP) and the REST Webservice with all entry points. The created class contains:
    • the declaration of members representing the items of record used (via MAPPING).
    • the declaration of different methods representing the different entry points of REST Webservice. A method for each entry point of REST Webservice.
    • a sCreation method for the Creation entry point.
    • a sRead method for the Read entry point.
    • a sModification method for the Modification entry point.
    • a Deletion method for the Deletion entry point.
    • a sReadAll method for the Read All Records entry point.
Testing a REST Webservice and debugging it
WINDEV and WEBDEV allow you to run the test of your REST Webservice in the debugger. In this case, all you have to do is include breakpoints in the code of Webservice procedures and run its test (GO).
To run the test of a REST Webservice and to debug it:
  1. Start WDADMIN. WDADMIN is the application server provided with WEBDEV. This application server is used to run the test locally of WEBDEV sites and Webservices developed with WEBDEV or WINDEV.
  2. Display (if necessary) the description of REST Webservice in the editor.
  3. Expand found in the quick access buttons and select "Debug the Webservice".
    The project is compiled. The following window appears.
  4. Select the test method:
    • Run the Webservice test via the test tool found in the editor: A tool is provided with WINDEV and WEBDEV, allowing you to run the test of each entry point of Webservice (see below).
    • Run the Webservice test with an external program: Choose this option if a specific program was developed to call the Webservice. The test mode is stopped when the executable stops running.
    • Run the Webservice test manually: The WINDEV or WEBDEV editor waits for an external call. For example, you have the ability to open a browser and to type the URL of the query corresponding to one of the entry points of Webservice whose test will be run. The query will be processed and a response will be returned in the browser.
  5. Click the "Run the test" button.

Test tool of Webservice: WDTestRest

The WDTestRest tool is provided with WINDEV and WEBDEV. This tool lists all entry points of Webservice whose test will be run.
The left pane represents:
  • the list of all entry points of Webservice,
  • the history of all tests run.
The right section displays the list of all entry points whose test was run in pane format.
To run the test of an entry point:
  1. Double-click an entry point in the left pane. A pane is opened on the right.
  2. Fill the URL. For example, replace the expected parameters between {...} by a real value.
  3. Select the type of authentication in the list.
  4. Type the header parameters if necessary.
  5. Click the "Send" button to run the test. The result is displayed.
    • The "Response" pane contains the result returned by the URL.
    • The "Status" value corresponds to the HTTP response code returned by the URL.
The link "Generate the WL code" is used to generate and retrieve the WLanguage code equivalent to the test run in order to include it in your project.
Generating the REST Webservice
To generate a REST Webservice:
  1. Generate the Webservice:
    • if the current configuration is the one of the Webservice:
      • on the "Project" tab, in the "Generation" group, click "Generate".
      • click the generation icon in the quick access buttons.
    • if the current configuration is not the one of the Webservice: select the desired generation from the quick access buttons.
  2. The Webservice generation wizard starts.
  3. Specify the Webservice name. By default, the Webservice name corresponds to the name of the current project.
  4. Validate.
  5. The deployment wizard is automatically started thereafter.
Deploying a REST Webservice

Deploying a Webservice

In order to be used, a Webservice must be deployed on a WEBDEV Application Server.
Several deployment methods can be used:
  • Deploying the Webservice in the CLOUD for PC SOFT applications.
  • Deploying the Webservice on a remote WEBDEV Application Server.
  • Creating a remote deployment package.
  • Creating a setup by physical media.
  • Creating a Webservice Docker image.
  • Deploying the Webservice via the test hosting service of PC SOFT.
  • Deploying the Webservice on the local computer.
The options for deploying a Webservice are identical to the options for deploying a WEBDEV site. For more details, see Deploying a site.

Special case: Deploying a Webservice and running its test on the local computer

The test of the created Webservice can be run on the developer computer. To do so, select "Deploy the Webservice on the local computer". This type of setup is available only if WEBDEV is available on the development computer. In this case, the application server used is the one of WEBDEV.
At the end of the setup, a screen with a link allows you to display the Webservice description.
The Webservice is ready to be used.
Calling a REST function through programming
RESTSend is used to call a function of a REST Webservice. To do so, you must:
  • Use a variable of type httpRequest to describe the REST function to call:
    • The URL property describes the address (URL) of the REST Webservice function.
    • The Method property describes the HTTP method used (GET, PUT, etc.).
    • The ContentType property describes the type of data to be passed as a parameter to the REST Webservice function.
    • The Content property contains the data to be sent as a parameter to the REST Webservice function.
    • the eventual parameters to pass.
  • Use a variable of type restResponse to retrieve the result of the REST function:
    • The StatusCode is used to get the response status code.
    • The Content property contains the response data.

For example

  • The following code example explains how to retrieve information about a customer identified by his number. A code 200 is returned if the customer does not exist.
    nCustomerNum is int
     
    nCustomerNum= 2
     
    h is httpRequest
    h.Method = httpGet
    h.URL = "http://localhost/V1/Customers/" + nCustomerNum
     
    r is httpResponse = RESTSend(h)
    IF r.StatusCode = 200 THEN
    Info(r.Content)
    ELSE
    Info("Customer not found", r.Content)
    END
  • The following code example explains how to delete a customer identified by his number. A code 404 is returned if the customer does not exist.
    nCustomerNum is int
     
    nCustomerNum= 267
     
    h is httpRequest
    h.Method = httpDelete
    h.URL = "http://localhost/V1/Customers/" + nCustomerNum
     
    r is httpResponse = RESTSend(h)
     
    IF r.StatusCode = 404 THEN
    Info("Customer NOT found.")
     
    ELSE
    Info("The customer was successfully deleted")
    END
  • The following example explains how to add a customer. A code 201 is returned if the customer was successfully added.
    NewCust is Buffer
    vCust is Variant
     
    vCust.CustomerName = "MOORE"
    vCust.Company = "MOORE Ltd"
    vCust.City = "LONDON"
     
    NewCust = VariantToJSON(vCust)
     
    h is httpRequest
    h.Method = httpPost
    h.URL = "http://localhost/V1/Clients"
    h.ContentType = "application/json"
    h.Content = NewCust
     
    r is httpResponse = RESTSend(h)
    IF r.StatusCode = 201 THEN
    Info(r.Content)
    ELSE
    Info("Error while creating customer", r.Content)
    END
Generating the OpenAPI definition
You can generate the OpenAPI definition of the REST web service: in the "REST Webservice" pane, in the "Options" group, select "OpenAPI documentation..." and select the location where the corresponding YAML file should be generated.
Minimum version required
  • Version 22
This page is also available for…
Comments
dead link in the page
step 3 method 1, "For more details, see Composition of resource.", the link just sends me back to step 3 method 1.
brys
20 Mar. 2024

Last update: 06/12/2023

Send a report | Local help