HowTo: Inserting data using a BC exposed as Rest service

This document explains how to insert new data using a Business Component exposed as a Rest web service in GeneXus.

First, let's see the basic guidelines:

How do I call the Rest service in GeneXus?

Use the HttpClient data type.

Which HTTP method should I use to insert new data?

The HTTP method used for inserting new data is the HTTP POST method.

How are the parameters going to be passed in the call?

All the parameters for inserting new data using the BC (except the PK parameters) need to be included in the body of the HTTP request. The message body should be in JSON format and contain the structure of the Business Component as it comes when it makes an HTTP GET.

The easiest way to build the body with the correct format is by defining an SDT based on the BC structure and using the ToJson method to format it to a valid JSON string.

That JSON string needs to be added to the body of the HTTP request before executing the POST to the service.

Which is the URL format to execute the POST?

<server uri>/rest/<module>/<bc name>/<param1>,<param2>,..,<paramN>

Where <param1>,<param2>,..,<paramN> is the compound Primary Key.

If the Primary Key is autonumbered, just use 0 in the URL.

Example

Consider the Product Business Component transaction that is exposed as a Rest web service, as shown in the figure below:

i2016_03_29_20_42_082_png

In this example, we want to insert a new Product, whose ProductId is 5.

Sample code

We've defined a ProductSDT structured data type based on the Product structure, as shown in the figure below:

i2016_03_29_20_51_373_png

Then, the code would be as follows:

&httpclient.Host= &server
&httpclient.Port = &port
&httpclient.BaseUrl = &urlbase

&productSDT.ProductName = "Samsung Galaxy"
&productSDT.ProductPrice = 22

&httpclient.AddString(&productSDT.ToJson())
&httpclient.AddHeader('content-type','application/json')
&httpclient.Execute('POST','Product/5')

if &httpclient.StatusCode = 201
    msg("Data successfully added")
else
   msg("There was an error retrieving the data: " + &httpclient.StatusCode.ToString())
endif

Download the sample from Sample insert data using a Rest BC

Notes:

  • Do not forget to add the 'content-type:application/json' header.
  • If more than one parameter should be passed in the URL (a compound PK), they need to be separated by commas.
  • If the service URI is "http://localhost/TestRESTFullGX.NetEnvironment/rest/Product", the BASE URL is: "/TestRESTFullGX.NetEnvironment/rest/"
  • Error handling is managed by querying the HTTP Status Code after the invocation.

See Also

Business Components as Rest web services in GeneXus