PC SOFT

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Home | Sign in | English US
  • Overview
  • Principle for calling a function of a REST Webservice
  • Creating a REST Webservice
  • The different steps
  • 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 return 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
  • Running the test of 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 by programming
  • Some examples
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadApple WatchUniversal Windows 10 AppWindows Mobile
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 an identical URL and different HTTP methods (representing a different action to perform).
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

The different steps

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 WLanguage procedure. 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.
Note: To run the test of REST Webservice, the Webservice must be deployed locally and it must be called via the client program. A debugging tool will be available in the Update 2.

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 window if necessary.
    • Click "Create a project".
  2. In the wizard for project creation:
    • Select a "SOAP or REST Webservice" project.
    • Choose to generate a REST Webservice.
  3. End the wizard.
To create a REST Webservice project configuration:
  1. On the "Project" pane, in the "Project configuration" group, expand "New configuration" and select "Webservice".
  2. In the wizard for generating a project configuration, choose to generate a REST Webservice.
  3. End 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" from the popup menu (right mouse click).
    Creating a Webservice description
  2. Type the name of the REST Webservice description and validate.
  3. The wizard for creating a new entry point is automatically started.

Step 3: Creating entry points

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

    Note: The "REST Webservice" pane is available only when a description of REST Webservice is displayed in the editor.
Versions 23 and later
If the project is associated with an analysis, the wizard for creating an entry point proposes to select the method for creating entry points:
New in version 23
If the project is associated with an analysis, the wizard for creating an entry point proposes to select the method for creating entry points:
If the project is associated with an analysis, the wizard for creating an entry point 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
    See Composition of resource for more details.
  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 by programming with WebserviceReadMIMEType).
    • Versions 23 and later
      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 procedure code to define the parameter and go back to the wizard for creating the entry point. 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.
        See REST WebServices: Automatic deserialization of request for more details.
      New in version 23
      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 procedure code to define the parameter and go back to the wizard for creating the entry point. 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.
        See REST WebServices: Automatic deserialization of request for more details.
      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 procedure code to define the parameter and go back to the wizard for creating the entry point. 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.
        See REST WebServices: Automatic deserialization of request for more details.
    • 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 by 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 wizard for resource creation, 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 wizard for URL creation, 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 by 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 run time, 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 is used have a resource section identical to all the 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.
Tip: The definition of common parameters can be used to manage different versions of the REST Webservice. For example, a common parameter named "V1" can be used. When creating an evolution or a version 2 of the Webservice, all you have to do is change "V1" to "V2" and all the entry points will have their resource (URL) modified.
To modify the common parameters, on the "REST webservice" pane, in the "Options" group, expand "Common components".

Managing return 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 return codes. The HTTP return codes are classified by family:
  • The 2xx codes correspond to an action successfully performed.
  • The 3xx codes correspond to redirection errors.
  • The 4xx codes correspond to client errors (incorrect HTTP method, incorrect data format sent, ...).
  • The 5xx codes correspond to server errors (internal error of WLanguage procedure, ...)
The return code is returned by WebserviceWriteHTTPCode.
Examples of return 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 in parameter via the GET method. This request was succesful: the code 200 will be returned.
  • Ask to find a product by passing a reference in parameter via the GET method. This request failed because the reference does not exist: the code 404 will be returned.
Versions 23 and later

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

In the rest of wizard for creating an entry point:
  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 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:
    • Creation: Add a record into the data file.
    • Read: Find and read a record in the data file.
    • Modification: Update a record in the data file.
    • Deletion: 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.
New in version 23

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

In the rest of wizard for creating an entry point:
  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 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:
    • Creation: Add a record into the data file.
    • Read: Find and read a record in the data file.
    • Modification: Update a record in the data file.
    • Deletion: 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.

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

In the rest of wizard for creating an entry point:
  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 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:
    • Creation: Add a record into the data file.
    • Read: Find and read a record in the data file.
    • Modification: Update a record in the data file.
    • Deletion: 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.
Running the test of 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 supplied 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 among the quick access buttons and select "Debug the Webservice".
    The project is compiled. The following window is displayed.
  4. Select the test method:
    • Run the Webservice test via the test tool found in the editor: A tool is supplied 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 supplied 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 return 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" pane, in the "Generation" group, click "Generate".
      • click the generation icon among the quick access buttons.
    • if the current configuration is not the one of the Webservice: select the requested generation among the quick access buttons.
  2. The wizard for generating the Webservice starts.
  3. Specify the Webservice name. By default, the Webservice name corresponds to the name of the current project.
  4. Select the elements that will be included in the Webservice. These elements correspond to anything but the interface elements (window, page, report, ...). Check the elements to include and the ones that will be called in the Webservice.
  5. Go to the next step.
  6. Select the accessible descriptions.
  7. The deployment wizard is automatically started thereafter.
To generate a REST Webservice:
  1. Generate the Webservice:
    • if the current configuration is the one of the Webservice:
      • on the "Project" pane, in the "Generation" group, click "Generate".
      • click the generation icon among the quick access buttons.
    • if the current configuration is not the one of the Webservice: select the requested generation among the quick access buttons.
  2. The wizard for generating the Webservice 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 on a remote WEBDEV application server.
  • Deploying the Webservice in the CLOUD for PC SOFT applications.
  • Deploying the Webservice via the test hosting service of PC SOFT.
  • Creating a remote deployment package.
  • Creating a setup by physical media.
  • Deploying the Webservice on the local computer.
The options for deploying a Webservice are identical to the options for deploying a WEBDEV site. See Deploying a site for more details.

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 setup, a screen with a link allows you to display the Webservice description.
The Webservice is ready to be used.
Calling a REST function by programming
RESTSend is used to call a function of a REST Webservice. To do so, you must:
  • Use a httpRequest variable to describe the REST function to call:
    • ..URL describes the address (URL) of the function of REST Webservice.
    • ..Method describes the HTTP method (GET, PUT, ...).
    • ..ContentType describes the type of data that will be sent in parameter to the function of REST Webservice.
    • ..Content contains the data that will be sent in parameter to the function of REST Webservice.
    • the eventual parameters to pass.
  • Use a restResponse variable to retrieve the result of REST function:
    • ..StatusCode contains the return error code.
    • ..Content contains the response data.

Some examples

  • 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 restResponse = 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 restResponse = 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/Customers"
    h..ContentType = "application/json"
    h..Content = NewCust

    r is restResponse = RESTSend(h)
    IF r..StatusCode = 201 THEN
    Info(r..Content)
    ELSE
    Info("Error while creating customer", r..Content)
    END
Minimum required version
  • Version 22
This page is also available for…
Comments
Click [Add] to post a comment