Invoking Operations that Retrieve Data from the Web Service (SELECT Queries)¶

There are two ways to pass input parameters to a Web service operation that executes SELECT queries:

1. Send an HTTP GET request with the parameters in the URL. The syntax is the following:

   http://host:port/server/databaseName/serviceName/{ rest|json|html|rss }/opName?paramName1=value1&paramNameN=valueN
   

   This syntax is valid to invoke any of the REST versions of the Web service: XML, JSON, HTML or RSS.

2. Or, send an HTTP POST request. The parameters of the query are sent in the body of the request.

   To invoke an XML, RSS or HTML service, add an XML document with the input parameters, to the body of the request and add the HTTP header Content-type=application/xml.

   To invoke a JSON service, add a JSON document with the input parameters, to the body of the request and add the HTTP header Content-type=application/json.

Example: Let us suppose that the testWS service has an operation called getINTERNET_INCBYIINCID with two input parameters called iinc_id and taxid. The operation can be invoked by sending a request to the following URLs:

Instead of putting the input parameters in the URL, you can send a POST request to the URL of the operation:

http://acme:9090/server/admin/testWS/{ rest | json | rss | html }/getINTERNET_INC

and send the input parameters in the body of the request. If you send a request to the REST (XML), RSS or HTML services, you can send an XML document like this one with the HTTP header Content-type=application/xml:

<internet_inc>
    <iinc_id>1</iinc_id>
    <taxid>12345678</taxid>
</internet_inc>

The root element of the XML document has to be the name of the view, except when you are invoking an operation that was created from the Publish from VQL expression dialog (see section Operations Tab). In this case, the root element has to be vql_operations and not the name of the view.

If you invoke the JSON service, you can send a JSON document like this one with the HTTP header Content-type=application/json:

{
  "iinc_id": 1,
  "taxid": "12345678"
}

When the Web service receives any of these requests, it will execute the following query:

SELECT IINC_ID, SUMMARY, TTIME, TAXID, SPECIFIC_FIELD1, SPECIFIC_FIELD2
FROM internet_inc
WHERE iinc_id = 1 AND taxid = '12345678'
CONTEXT ('i18n' = 'us_pst')

If the type of an input parameter of an operation is compound (register or array), its value is represented by using the ROW and {} VQL constructors (see the section Conditions with Compound Values of the VQL Guide for more details about representing compound).

The format of the result will depend on the Web service version you are invoking. If you invoke the XML Web service, you will obtain a XML document, if you invoke the JSON Web service, you will obtain a JSON document, etc.

Example of invoking a Web service with compound parameters: Let us suppose that the testWS Web service has an operation called getREVENUESUM. This operation publishes the view REVENUESUM created in the section Creating Conditions with the Compound Values Editor, which has an input parameter of type array called clients. Each record of the array has one text field that represents a company’s tax identifier. The operation returns the sum of the revenue of the companies in the input parameter. The URL to invoke the REST version of this operation is:

http://acme:9090/server/admin/testWS/rest/getREVENUESUM?clients={ROW('B78596011'),ROW('B78596012')}

By default, the REST, JSON and HTML Services return an error if a client passes parameters in the URL that do not belong to the published view. If a client needs to ignore the extra parameters, it must add the validateparams parameter to the URL.

For example, if a client invokes the following URL, the Service returns an error because made_up_parameter does not belong to the published view.

http://acme:9090/server/admin/testWS/rest/getINTERNET\_INC/?made\_up\_parameter=1

However, if a client invokes the following URL, the Service will ignore made_up_parameter and return the result of the query.

http://acme:9090/server/admin/testWS/json/getINTERNET\_INC/validateparams/false?made\_up\_parameter=1

The parameter validateparams has to be added to the URL after the name of the operation and is valid for the REST, JSON, HTML and RSS services.

Invoking Operations that Insert New Data (INSERT Queries)¶

There are three ways to pass input parameters to a Web service operation that executes INSERT queries:

1. Send a GET request with the parameters in the URL. The syntax is the following:

   {rest|json|html|rss}/opName?paramName1=value1&paramNameN=valueN
   

   This syntax is valid to invoke any of the REST versions of the Web service: XML, JSON, HTML or RSS.

2. Send an HTTP POST request.

3. Or, send an HTTP PUT request.

For options 2 and 3 the input parameters are sent in the body of the request.

The request sent to the XML (REST), RSS and HTML versions of the Web service must have:

• The HTTP header Content-type=application/xml

• A body with an XML document, which contains the input parameters of the operation.

The request sent to the JSON version of the Web service must have:

• The HTTP header Content-type=application/json

• A body with a JSON document, which contains the input parameters of the operation.

Example

Let us say that we have published a Web service with an operation insertINTERNET_INC that executes an INSERT query on the view internet_inc. The parameters of this operation are IINC_ID, SUMMARY, TTIME, TAXID, SPECIFIC_FIELD1 and SPECIFIC_FIELD2.

If you send a POST or PUT request with the header Content-type=application/xml, the body of the request has to contain an XML document like this one:

<internet_inc>
    <IINC_ID>100</IINC_ID>
    <SUMMARY>New incident</SUMMARY>
    <TAXID>12345678</TAXID>
    <TTIME>Aug 22, 2011 1:04:22 PM</TTIME>
    <SPECIFIC_FIELD1>3</SPECIFIC_FIELD1>
    <SPECIFIC_FIELD2><![CDATA[specific info]]></SPECIFIC_FIELD2>
</internet_inc>

When the operation receives this document, executes the following query:

INSERT INTO internet_inc
    (iinc_id, summary, ttime, taxid, specific_field1, specific_field2)     VALUES
    (100,
     'New incident',
     TO_DATE('MMM d, yyyy h:mm:ss a', 'Aug 22, 2011 1:04:22 PM'),
     '12345678',
     '3',
     'specific info')
CONTEXT ('i18n' = 'us_pst')

Note that the value of the field SPECIFIC_FIELD2 of the XML document contains a CDATA section, which is properly treated as you can see in the executed query.

If you send a POST or PUT request with the header Content-type=application/json, the body of the request has to contain a JSON document like this one:

{
    "IINC_ID": 100,
    "SUMMARY": "New incident",
    "TTIME": "Aug 22, 2011 1:04:22 PM",
    "TAXID": "12345678",
    "SPECIFIC_FIELD1": "3",
    "SPECIFIC_FIELD2": "specific info "
}

The type of the parameter TTIME is date. This means that the value of the element in the JSON or XML document must have the format expected by the I18N of the query associated with the operation of the Web service. The result of the statement DESC VQL WEBSERVICE <web service name>, contains the query associated with each operation (parameter VQL of the parameter OPERATION).

Invoking Operations that Update Data (UPDATE Queries)¶

There are three ways to pass input parameters to a Web service operation that executes UPDATE queries:

1. Send an HTTP GET request with the parameters in the URL. The syntax is the following:

   http://host:port/server/databaseName/serviceName/{ rest|json|html|rss }/opName?paramName1=value1&paramNameN=valueN
   

2. Send an HTTP POST request.

3. Or, send an HTTP PUT request.

For options 2 and 3 the input parameters are sent in the body of the request.

The request sent to the XML (REST), RSS and HTML services must have:

• The HTTP header Content-type=application/xml

• A body with an XML document, which contains the input parameters of the operation.

The requests sent to the JSON services must have:

• The HTTP header Content-type=application/json

• A body with a JSON document, which contains the input parameters of the operation.

Example

Let us say that we have published a Web service with an operation updateINTERNET_INC that executes an UPDATE query on the view internet_inc. This view has the following fields:

• IINC_ID

• SUMMARY

• TTIME

• TAXID

• SPECIFIC_FIELD1

• SPECIFIC_FIELD2

So this operation will have the following input parameters:

• IINC_ID

• SUMMARY

• TTIME

• TAXID

• SPECIFIC_FIELD1

• SPECIFIC_FIELD2

• NewIINC_ID

• NEWSUMMARY

• NEWTTIME

• NEWTAXID

• NEWSPECIFIC_FIELD1

• NEWSPECIFIC_FIELD2

As we explained in the section Operations Tab, the parameters with the prefix NEW are the new values of the fields of the selected rows. The parameters that do not have the prefix NEW are used to select the affected rows.

If you send a POST or PUT request with the header Content-type=application/xml, the body of the request has to contain an XML document like the following:

<internet_inc>
    <IINC_ID>155</IINC_ID>
    <NEWIINC_ID>155</NEWIINC_ID>
    <NEWSUMMARY>Error in ADSL router</NEWSUMMARY>
    <NEWTTIME>Jun 6, 2005 10:19:41 PM</NEWTTIME>
    <NEWTAXID>B78596011</NEWTAXID>
    <NEWSPECIFIC_FIELD1>1</NEWSPECIFIC_FIELD1>
    <NEWSPECIFIC_FIELD2>1</NEWSPECIFIC_FIELD2>
</internet_inc>

When the operation receives a request with this XML document, executes the following query:

UPDATE internet_inc SET
    iinc_id=155,
    summary = 'Error in ADSL router',
    ttime = TO_DATE('MMM d, yyyy h:mm:ss a', 'Jun 6, 2005 10:19:41 PM'),
    taxid = 'B78596011',
    specific_field1 = '1',
    specific_field2 = '1'
WHERE
    iinc_id = 155
CONTEXT ('i18n' = 'us_pst')

Invoking Operations that Delete Data (DELETE Queries)¶

There are three ways to pass input parameters to a Web service operation that executes DELETE queries:

1. Send an HTTP GET request with the parameters in the URL. The syntax is the following:

   http://host:port/server/databaseName/serviceName/{ rest|json|rss }/opName?paramName1=value1&paramNameN=valueN
   

2. Send an HTTP DELETE request. The parameters also have to be sent in the URL as with the GET method.

3. Send an HTTP POST request. The input parameters are sent in the body of the request sent to the Web service. The POST request must have:

   • If the request is sent to the XML (REST) and RSS versions of the Web Service, the HTTP header Content-type=application/xml and a body with an XML document, which contains the input parameters of the operation.

   • If the request is sent to the JSON version of the Web Service it must contain the HTTP header Content-type=application/json and a body with a JSON document, which contains the input parameters of the operation.

Example

Let us say that we have published a Web service with an operation deleteINTERNET_INC that executes a DELETE query on the view internet_inc. The parameters of this operation are IINC_ID, SUMMARY, TTIME, TAXID, SPECIFIC_FIELD1 and SPECIFIC_FIELD2.

If you send a DELETE request, the URL of the request must be like this:

http://host:port/server/databaseName/serviceName/rest/deleteINTERNET?IINC_ID=1

If you send a POST request with the header Content-type=application/xml, the body of the request has to contain an XML document like this:

<internet_inc>
    <IINC_ID>1</IINC_ID>
</internet_inc>

If you send a POST request with the header Content-type=application/json, the body of the request has to contain a JSON document like this:

{
    "IINC_ID": 1,
}

When the operation receives any of these requests, it executes the following query:

DELETE FROM internet_inc
WHERE IINC_ID = 1
CONTEXT ('i18n' = 'us_pst')