Example: a REST Service for manipulating data (UPDATE)

In this example, you change the name of a customer that already exists in the database.

This example shows how you can quickly generate a REST service from a SQL statement.

In this particular example, an input parameter is used that is part of the request URL path, but you have a number of other options when designing input parameters.

Defining SQL

1.	In the User Application, in SQL Command, write and test a SQL statement that will change the first name or family name (or both) of an existing customer identified by PERSON_ID, for example:

update person

set

(

first_name

, family_name

) =

(

select 'Mary'

, 'CARRINGTON'

)

where person_id = 173

2.	In USoft Services Definer, create a variant of this statement that indicates the REST input parameters. To do this, choose Define, SQL Statements from the menu, then create a statement record with the following values:

•Statement name: SET_PERSON_NAMES

•Application name: TRAVEL

•Statement:

update person

set

(

first_name

, family_name

) =

(

select :MyPersonNameStructure.FirstName

, :MyPersonNameStructure.SurName

)

where person_id = :id

Notice that the ID used to identify the individual customer is passed as a standard input variable introduced by a colon (":id"), whereas the name values are passed as elements of a structure called "MyPersonNameStructure".

This design is followed through in the entire REST design: the caller passes the ID as part of the request URL, and the name information as part of an XML message.

3.	Save work. Click the Check button to have your SQL syntax checked. If it is correct, the Correct = Yes flag is set.

Generating a REST method based on SQL

1.	Define a custom REST service and make sure that this new service is exposed by a Server. For details on how to do these 2 things, step out to help topic " Setting up your own REST service ".

2.	On the Methods tab, create a record for the retrieval method:

•Method Name = PutPersonNames

•Relative URI Path = /PersonNames

•REST HTTP Verb = PUT

3.	Press the "Generate from SQL" button.

The "Generate Method from SQL Statement" dialog appears.

4.	On the SQL Statements tab, click in the record for the statement that you want the REST method to be generated from.

5.	Press the Generate button.

In the REST Services window or tab, values for Signature, Implementation and Parameters are generated.

In the Catalog on the left-hand side, a Structure with name MyPersonNameStructure is offered for inspection.

6.	Save work.

Organising input for the ID parameter

With the following steps, you organise the passing of the customer ID as part of the request URL:

1.	In the REST Services window, make sure you have your REST service in view. On the Methods tab, make the following setting:

•Relative URI Path = /PersonNames/{id}

2.	On the Parameters tab for this method, make the following setting for the id parameter:

•Annotation = @PathParam("id")

Publishing the solution

1.	Choose Define, Servers, and retrieve the record of the Server where you expose the service.

2.	With input focus on this record, choose Publish, Publish and Restart from the menu.

Testing the implementation

1.	Open a Google Chrome browser window, search the download site for the “POSTMAN – REST Client” Google extension, and download it to your browser.

Once installed, this extension can be opened easily from a new Google Chrome browser tab. To do this, click the standard “Apps” button on the Favorites bar, then click the POSTMAN item in the middle of the screen.

2.	Open POSTMAN, and specify the following URL:

http://<host-name>:<port-number>/<service-uri>/<method-uri>/<id-parameter-value>

for example:

http://localhost:8090/mycustomservice/PersonNames/17

3.	Set the HTTP verb to PUT.

You are given a form in which to submit a message.

4.	Specify that your message is XML, then submit the following message:

<FirstName>Johnny</FirstName>

<SurName>LOGAN</SurName>

</MyPersonNameStructure>

5.	Press the Send button.

See that HTTP status code "200 OK" is returned as a response. In the User Application, check that the record with ID = 17 in the PERSON table has been correctly updated with the new name values.

Another popular design of this type of REST call is to pass back the result data in a response message. For this design, go to help topic " Example: a REST Service for returning manipulated data ".