This help topic tells you how to define a REST service that is NOT predefined, that is, a REST service that you either generate yourself from SQL or that you program yourself as a custom REST service.
By default, non-predefined REST services are based on the "USoft REST Default Provider" functional type that USoft ships with the Service Definer product. Alternatively, you may want to use a different USoft default provider, or you may prefer to create a functional type of your own.
If you use the "USoft REST Default Provider" functional type, you can use the "Generate from SQL" utility to have a first working version of the target code generated by USoft. For an example of this, go to " Example: a REST service for retrieving data ".
To define a REST service of a non-predefined type:
|1.||Choose Define, REST Services from the menu.|
|2.||Insert a new "REST Services" record and set its Service Name value to mycustomservice.|
|3.||If you want to use the ready-made USoft-shipped default for non-predefined services, click the lookup button at the Functional Type field and select 'USoft REST Default Provider'.|
|Alternatively, if you want to use an existing Java class of your own, read the NOTE at the end of this section.|
|4.||Save work. Defaults are generated for Package and for Relative URI Path. Change these if appropriate.|
|5.||Press the Check button on the right-hand side.|
|This causes the 'mycustomservice' REST Service to get the Correct = Yes setting.|
NOTE: To use an existing Java super class, base class or interface, declare that Java package by creating a record in table T_SVC_SUPER_CLASS. To do this, choose View, Objects from the menu, click on "SVC Super Classes" and fill out the form, taking USoft-shipped entries as an example. Enter a Functional Name as a unique handle for the code. Enter a Description and set Used for Class Type = REST Service. Save. You can now use the Functional Name when you select a functional type in Step 3.
To associate your REST service with a server:
|1.||Choose Define, REST Services from the USoft Service Definer menu.|
|The "REST Services" window or tab appears.|
|2.||Query the REST service that you want to expose.|
|3.||When you have that REST service in view, click the Servers tab and specify the server where you want to publish the REST service, for example, the default server called 'Default'.|
|TIP: Get a list of available servers by pressing, in the Servers tab, the F12 key.|
To associate the custom REST service with a connection:
|1.||In the "REST Services" window, for the REST service, click the Connections tab and specify the connection that you want the service to use. |
|To get a list of available connections by pressing, in the Connections tab, the F12 key.|
To (re)publish the custom REST service at the server:
|1.||Choose Define, Servers from the menu of the USoft Service Definer.|
|The Servers window or tab appears.|
|2.||Query the server where you want to (re)publish the REST service.|
|3.||Stop the Server if it was running. Do this by choosing Actions, Stop from the menu, or by clicking the Stop icon on the icon ribbon.|
|4.||(Re)publish the service(s) associated with the server. Do this by choosing Publish, Publish Services from the menu, or by clicking the Publish Services icon on the icon ribbon.|
|5.||Start the Server. Do this by choosing Actions, Start from the menu or by clicking the Start icon in the icon ribbon.|
TIP: You can wrap Steps 3, 4 and 5 into one by choosing Publish, Publish and Restart from the menu or by clicking the "Publish and Restart" icon on the icon ribbon.
Once you have a USoft REST service running, you can test its behaviour by using any favourite app.
As an example, the following steps describe how you can use the POSTMAN app.
|1.||Open a Google Chrome browser window, search the download site for the “POSTMAN – REST Client” Google extension, and download it to your browser.|
|2.||Click the standard “Apps” button on the Favorites bar, then click the POSTMAN item in the middle of the screen.|
You are now ready to define one or more methods for your custom REST service.
Defining REST methods
Designing a REST service