REST web service: Creating entry points

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / /

Creating entry points
Method 1: Manual creation of an entry point
Method 2: Automatic creation of entry points to access a data file
Method 3: Creation of entry points from a class or set of procedures
Remarks
Resource structure (or URL section)
Status codes in the code of procedures

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

REST web service: Creating entry points

Creating entry points

The REST web service entry point creation wizard opens:

when creating a new REST web service description.
on the "REST web service" tab, "Entry points" group, by clicking "New".

Note: The "REST web service" tab only appears when you open a REST web service description in the editor.

The entry point creation wizard lets you select the creation method:

Method 1: Manual creation of entry points.
Method 2: Automatic creation of entry points from the description of a data file (present in the analysis).
Method 3: Automatic creation of entry points from a set of procedures.

Method 1: Manual creation of an entry point

To manually create an entry point:

In the wizard, select "Create an entry point".
Go to the next step.
Specify the global WLanguage procedure associated with the entry point. This procedure can be created or selected from existing global procedures.
Go to the next step.
Choose the HTTP method according to the desired action (GET, PUT, etc.).
Go to the next step.
Define the resource (or URL section) corresponding to the entry point. This resource can include static elements or variable elements (parameters).

For more details on the resource, see Resource structure..
Go to the next step.
Define the request and response format. JSON is the standard format in REST web services, but other formats are also available.
- The request format indicates how the data passed in the REST call is formatted.
  
  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 must be specified using WebserviceReadMIMEType).
- Automatic deserialization: The data passed as parameters to POST, PUT or PATCH requests can be automatically deserialized in a parameter of the procedure associated with the entry point:
  
  Check "Automatically deserialize the request content in a parameter of the procedure associated with the entry point.".
  Note: If no parameters have been defined for the procedure, this checkbox is disabled.
  Select the name of the target parameter in the list.
  Important: The procedure code must be able to handle the target parameter. It is necessary to specify the type of the procedure parameter. The following types of parameters are allowed in the procedure: Buffer, ANSI string, Structure, Array, Object. Simple types (integer, date, time, boolean, etc.) are not allowed.
  For more details, see REST web services: Automatic request deserialization.
  Note: If there are changes to be made to the procedure, you can configure the automatic deserialization from the REST web service description window.
- The response format indicates how the data retrieved from a REST call is formatted.
  
  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 must be specified using WebserviceWriteMIMEType).
Go to the next step.
Type the entry point description (free text).
Confirm.

The description of the different entry points is displayed in the editor.

Method 2: Automatic creation of entry points to access a data file

To automatically create entry points and procedures for a data file in the analysis:

In the wizard, select "Create entry points to access data files".
Select the data file for which you want to define the entry points.
Go to the next step.
Select the items that will be exposed in the web service.

These items can be accessed in read and/or write mode via the REST web service entry points.
Go to the next step.
Select the key that will be used to access the record in the data file to be read, modified or deleted.
Go to the next step.
Select the format used to exchange data when calling the entry points of the REST web service. 3 formats are available:
- JSON (UTF-8): Data sent or returned is in JSON format.
- JSON (UTF-8) (HRecordToJSON): Data is formatted in an intermediate object created with HRecordToJSON.
- XML: Data sent or returned is in XML format.
Go to the next step.
Select the list of entry points that will be generated when creating the REST web service.

By default, all types of entry points are generated:
- Creation: Add a record into the data file.
- Read: Find and read a record in a 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.
Go to the next step.
That's all. The wizard generates the object-oriented (OOP) source code and the REST web service with all entry points. The created class contains:
- the declaration of members representing the items of the record being manipulated (MAPPING).
- the declaration of methods representing the different REST web service entry points. A method for each entry point of REST web service.
- 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.

Method 3: Creation of entry points from a class or set of procedures

To automatically create entry points from a class or set of procedures:

In the wizard, select "Create entry points from the procedures of a set".
Select the set of procedures or the class associated with the entry point.
Go to the next step.
Select the procedures or methods that will be exposed by the REST web service. The resource associated with each procedure or method will be automatically initialized according to the name of the procedure and its parameters.

Specify the HTTP method for each selected procedure.
Go to the next step.
Define the request and response format. JSON is the standard format in REST web services, but other formats are also available.
- The request format indicates how the data passed in the REST call is formatted.
  
  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 must be specified using WebserviceReadMIMEType).
- The response format indicates how the data retrieved from a REST call is formatted. 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 must be specified using WebserviceWriteMIMEType).
Finish the wizard.

The description of the different entry points is displayed in the editor.

Remarks

Resource structure (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, etc.). For example, "/Customers/{CustNum}" identifies the customer using a customer number.

In the URL creation wizard, a variable element corresponds to:
- a variable component defined by a procedure parameter. This component is automatically retrieved in the parameters of the associated WLanguage procedure.
- a variable component retrieved programmatically with WebserviceParameter.
A variable element is represented by the following syntax: "{Variable component name}".
For example, "/Customers/10" allows you to manage customers with an identifier set to 10.
It is quite common to pass variables elements in the URL when calling a REST function.
Each variable component (retrieved programmatically) of the resource 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 retrieved programmatically, this name must be identical to the name of the parameter 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 vice versa), otherwise a runtime error occurs.

You can combine several static and variable elements. For example:

"/Customers/{CustomerID}/Invoices" to retrieve the invoices of a customer identified by their customer ID.
"/Suppliers/{SupID}/Products/{ProdRef}" to retrieve the product identified by "ProdRef" for the supplier identified by "SupID".

To change the common parameters, go to the "REST web service" tab, "Options" group, and select "Description".

In the "Common components" tab of the REST webservice description window, you can define a part of the resource that is common to all entry points. Therefore, there is no need to systematically copy this resource section to each entry point. The modification is performed at a single location.

Tip: You can use common parameters to manage different versions of the REST web service. For example, you can use a common parameter named "V1". When creating another version of the web service, simply change "V1" to "V2" to change the resource (URL) of all entry points.

Status codes in the code of procedures

The code of WLanguage procedures used for REST web services must manage reports indicating whether or not the function has been executed successfully.

In a REST web service, execution reports are returned using HTTP response status codes. HTTP response codes are divided into different categories:

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:

Create a customer using the POST method. If the request was successful, return code 201.
Delete a customer using the DELETE method. If the request fails due to an integrity error returned by the database, return code 500 with a message explaining the error.
Find a product by passing a reference as parameter via the GET method. If the request was successful, return code 200.
Find a product by passing a reference as parameter via the GET method. If the request fails because the reference does not exist, return code 404.