Using the IBM InfoSphere Guardium REST API

Automate, integrate, and innovate with data security and compliance software from IBM

Organizations that use IBM® InfoSphere® Guardium® for data security and compliance can take advantage of a rich set of APIs to automate processes and maintain their systems very efficiently. In InfoSphere Guardium 9.1, the Guardium API is exposed to external systems as online RESTful web services, which provide a modern interface to expose Guardium capabilities in a web portal or via the cloud. In this article, learn how the new enhancements can be useful in your environment.

Guy Galil (guyga@il.ibm.com), Technical Lead, IBM

Guy GalilGuy Galil has been working with Web Services and Service Oriented Architecture (SOA) even before these terms were coined. He has been with Guardium since its inception in 2003 and was involved in the design and implementation of most of its back-end modules. Guy designed and implemented the GrdAPI framework and led the development of the REST API implementation.



Yaacov Lacher (yaacovl@il.ibm.com), Software Engineer, IBM

Yaacov LacherYaacov Lacher has a BS degree in computer science from Ben-Gurion University and is currently pursuing a master of business administration at the Hebrew University. He served as an expert on software security and encryption in the Israeli Defense Forces (IDF).



Oded Sofer (ODEDSO@il.ibm.com), Senior Business Analyst Manager, IBM

Oded SoferOded Sofer was the product manager at Guardium, PS director at DB-Motion Interoperability solution for Healthcare, and chief designer and VP of eProduct at Viryanet. He led and designed diverse, innovative, and pioneering products for integration and interoperability.



Kathy Zeidenstein (krzeide@us.ibm.com ), InfoSphere Guardium Evangelist, IBM

Kathy ZeidensteinKathy Zeidenstein has worked at IBM for a bazillion years. Currently, she is working as a technology evangelist for InfoSphere Guardium data activity monitoring, based out of the Silicon Valley Lab. Previously, she was an Information Development Manager for InfoSphere Optim data lifecycle tools. She has had roles in technical enablement, product management and product marketing within the Information Management and ECM organizations at IBM.



17 April 2014

Introduction to InfoSphere Guardium

InfoSphere Guardium is the product family name for a set of data security and compliance solutions from IBM. It includes data activity monitoring, vulnerability assessment, data encryption, and document redaction capabilities.

In this article, learn about the enhancements to the heritage Guardium product line that was acquired by IBM in 2009 and is now known as InfoSphere Guardium Data Activity Monitor and InfoSphere Guardium Vulnerability Assessment solution. Both of these solutions rely on an InfoSphere Guardium server hardware or software appliance, as shown in Figure 1. InfoSphere Guardium capabilities are configurable from a single server.

Figure 1. InfoSphere Guardium
InfoSphere Guardium capabilities are configurable from a single server

InfoSphere Guardium is designed to scale from very small to extremely large deployments from both an architectural and total cost of ownership (TCO) perspective. A federated architecture lets the solution grow to monitor hundreds and thousands of database servers. From a TCO perspective, InfoSphere Guardium includes:

  • Automation features such as scheduling.
  • A feature-rich API that exposes Guardium back-end functions.
  • Scripting.
  • External systems for automation and integration purposes.

Almost everything that you can do in InfoSphere Guardium from the user interface can also be done using an API from the command line interface (CLI). Tasks such as querying or setting appliance configurations, security policy definitions, report execution, population of Guardium groups, and much more are easily accomplished using the API. Tedious, high-volume tasks such as defining thousands of data sources or software TAPS (S-TAPS) can be scripted and automated using the Guardium API. For details on the Guardium API, see the Guardium Tech Talk or the Guardium API Reference (in Resources).

Beginning with InfoSphere Guardium 9.1, the Guardium API is now exposed to external systems as online RESTful web services. To use the capabilities described in this article, you need a minimum of GPU 200 of that release. The goal is to enable organizations that use Guardium to use a modern interface for exposing capabilities to their users, such as in a web portal or via the cloud.

Discussion of REST programming is outside the scope of this article. See Resources for information about REST.

Representational State Transfer (REST) has gained wide acceptance as the preferred architectural style for implementing web services and as a simpler alternative to SOAP and WSDL. Many organizations promote a RESTful interface as a way to expose their services and to interface with other services.


Use cases

Guardium users will likely have creative ideas on using the new RESTful APIs. The following are just a few examples of use cases.

  • Keeping database permissions in synch with groups in Guardium in order to react quickly to changes in personnel. For example, when organizations bring on new DBAs, those DBAs require increased monitoring because of their privileged status. A traditional way to do this in Guardium is to use an entitlement report to import the data and then populate the DBA group using a query on that imported information. However, it is impractical to make the updates immediate. For instance, if someone was granted the DBA role in Oracle, it might take a day for the entitlement report to refresh and then the policy to get installed.

    With the REST API, you could send a syslog event to a receiver when a grant is made to the DBA role, and then that receiver could fire some API calls to update the group of administrative users and reinstall the policy. This would dramatically reduce the gap between when permissions are updated and when logging levels are bumped up for users. Or, you could implement a custom alerter with Java to fire the calls directly from the Guardium system itself.

  • Requiring one set of users, such as IT users, to be tracked differently from other users. You can import user lists from LDAP to fulfill this requirement, but there's a delay that could be eliminated by making REST API calls during the on-boarding applications, such as building a hook into the enterprise directory.
  • Mitigating the risk caused by time delays in off-boarding personnel and revoking their credentials. If someone leaves an organization, it can often take a long time to get their credentials revoked from the databases. InfoSphere Guardium can quarantine users immediately. REST API calls could be made as part of the off-boarding applications to apply quarantine to their accounts in anticipation of this event.

It is important to understand that the REST API is good for an online interface such as retrieving the data of a specific report, adding policy rules, managing groups, or defining datasources. It is not the right method for high volume data offload.


The basics

REST web services use the HTTP methods (verbs) GET, POST, PUT, and DELETE. They use JSON as the payload format because it is much lighter than XML.

Existing Guardium API functions have been mapped to the appropriate verb and resource so you can construct the REST URL. For example, a fundamental task in Guardium is managing groups and their members. For the REST API, group is the resource, and the appropriate REST verbs depend on what the desired action is. Table 1 shows an example.

Table 1. Mapping group functions to REST verbs and resources
Function nameREST verbREST resource
list_group_by_descGETGroup
create_groupPOSTGroup
delete_group_by_descDELETEGroup

To manage members of groups, we defined member as the resource, as in Table 2.

Table 2. Mapping member functions to REST verbs and resources
Function nameREST verbREST resource
list_group_members_by_descGETMember
create_member_to_group_by_descPOSTMember
delete_member_from_group_by_descDELETEMember

Policies are also key to working with InfoSphere Guardium. You use policies to determine what activities to monitor and what actions to take when certain conditions occur, such as unauthorized access to sensitive data or access by unknown connections. Policies can be updated as conditions change, and different policies can be in effect at different times. Table 3 shows examples of REST API capabilities around policies. (Table 4 actually has the API you would use to install a policy after updating it or after a change in a group that the policy uses.)

Table 3. Mapping policy functions to REST verbs and resources.
Function nameREST verbREST resource
create_policyPOSTPolicy
update_policyPUTPolicy
delete_policyDELETEPolicy
list_policyGETPolicy

Table 4 has some additional functions in which the resource is the same as the existing GRDAPI function name.

Table 4. Resource is the same as the function name
Function nameREST verbREST resource
policy_installPOSTpolicy_install
patch_installPUTpatch_install
reset_unit_utilization_dataPUTreset_unit_utilization_data
stop_audit_processPUTstop_audit_process

There are hundreds of API functions. For your convenience, we expose the REST API resource to allow querying (GET) for available resources and their parameters. You do need an authorization token for this, as described in Authorization flow. Listing 1 shows an example of querying resources.

Important: For readability, all curl command lines were broken; enter the actual commands as a single line.

Listing 1. Example of querying resources
Request: 
curl -k -i --header "Authorization:Bearer 80cdcfa3-e02e-4bd6-829a-6b656beaa90a" 
	https://10.10.9.248:8443/restAPI/restapi
Response:  
[
  {
    "resource_id": 1,
    "api_function_name": "create_datasource",
    "resourceName": "datasource",
    "verb": "POST"
  },
  {
    "resource_id": 2,
    "api_function_name": "list_datasource_by_id",
    "resourceName": "datasource",
    "verb": "GET"
  },.....

The output includes the GrdAPI function name for reference.

The request in Listing 2, specifying withParameters=true, returns a detailed description, including the parameters of the REST API functions.

Listing 2. Query resources to include parameter details withParameters=true
Request: 
curl -k -i --header "Authorization: Bearer 8f8e5634-5714-4d3b-bcd8-a2f26bc768f3" 
        https://10.10.9.248:8443/restAPI/restapi?withParameters=true        
Response:
 [
   {	
    "resource_id": 678,
    "api_function_name": "list_classifier_policy",
    "resourceName": "classifier_policy",
    "verb": "GET",
    "parameters": [
      {
        "parameterName": "policyName",
        "parameterType": "java.lang.String",
        "isRequired": false
      },
      {
        "parameterName": "ruleName",
        "parameterType": "java.lang.String",
        "isRequired": false
      },
      {
        "parameterName": "actionName",
        "parameterType": "java.lang.String",
        "isRequired": false
      },
      {
        "parameterName": "recursive",
        "parameterType": "java.lang.Boolean",
        "isRequired": false
      },
      {
        "parameterName": "api_target_host",
        "parameterType": "java.lang.String",
        "isRequired": false
      }
    ]
  },
  {
    "resource_id": 670,
    "api_function_name": "update_classifier_policy",
    "resourceName": "classifier_policy",
    "verb": "PUT",
    "parameters": [
      {
        "parameterName": "policyName",
        "parameterType": "java.lang.String",
        "isRequired": true
      },
      {..........

To get the parameter list of a specific API function, you can specify the resource ID for that function, as in Listing 3. We request the information for resource ID 678, which corresponds to the API list_classifier_policy in the previous listing.

Listing 3. Querying a resource using the resource ID
Request: 
curl -k -i --header "Authorization: Bearer 1ece8a8a-e60d-47a3-a4f4-d7703bb7c7c9" 
        https://10.10.9.248:8443/restAPI/restapi?resourceId=678
Response:
[
  {
    "parameterName": "policyName",
    "parameterType": "java.lang.String",
    "isRequired": false
  },
  {
    "parameterName": "ruleName",
    "parameterType": "java.lang.String",
    "isRequired": false
  },
  {
    "parameterName": "actionName",
    "parameterType": "java.lang.String",
    "isRequired": false
  },
  {
    "parameterName": "recursive",
    "parameterType": "java.lang.Boolean",
    "isRequired": false
  },
  {
    "parameterName": "api_target_host",
    "parameterType": "java.lang.String",
    "isRequired": false
  }
]

Authorization flow

Security is a major concern when allowing external interface to the InfoSphere Guardium system. When the API is used interactively or through scripts, the CLI or GUI frameworks ensure proper authentication.

When the APIs are exposed as a web service, it is necessary to enforce the authentication and authorization of each request. We chose OAuth2 as the authorization protocol and use the established Spring Security framework to implement it. See Resources for information on OAuth2 and the Spring Security framework.

Figure 2 shows an overview of the authorization flow.

Figure 2. Authorization flow
Each step in the flow is described in text below

The following numbered steps correspond to the numbers in Figure 2.

  1. The Guardium administrator must use a local CLI-authenticated session to generate a client secret for the client application.
  2. Store the client secret in a secure place.
  3. The client secret is then used by the client application to request an access token associated with a valid Guardium user.
  4. The client application saves that access token, which has a default expiration age of three hours.
  5. Subsequent API calls must specify the token and will have the permissions as granted to the user associated with the token. Any requests after the token expires will fail and the client application must generate a new token.

You can use the API functions getOAuthTokenExpirationTime and setOAuthTokenExpirationTime to display and modify the token expiration duration. This setting is global and affects all tokens. These API functions are not exposed as REST APIs and can be invoked only through an authenticated CLI session by a user with the admin role.

An access token can be revoked using the revokeOauthToken API function. A client ID can be revoked (invalidating all active tokens) using the revokeOauthClient API function.

Register as a client application to the InfoSphere Guardium server

To use the REST API, an application must have proper credentials. InfoSphere Guardium uses the OAuth process to provide a client secret that is used later to obtain proper credentials. You generate the client secret, which is a one-time process, when you register a new application with the server using a Guardium API command.

The registration API function accepts a client_id and returns a client secret that can be used to generate access tokens. A CLI user can do this either locally or through the SSH session to the Guardium appliance via the CLI user. You cannot use a REST API to do the registration. This registration must be done to each Guardium appliance that will be accessed by the client application.

Listing 4 shows an example of invoking a Guardium API command to register the client application. Note that the client_id parameter is used to identify the client and should be a meaningful name.

Listing 4. Invoking Guardium API command to register client application
v9GA.ibm.com> grdapi register_oauth_client client_id=client_id1 
ID=0
{"client_id":"client_id1","client_secret":"3ac89782-ce55-4f24-b795-b6c76ecc4045",
 "grant_types":"password","scope":"read,write","redirect_uri":"https://joeApp"}
ok

In the output above, you can ignore all but the client_secret.

The client_secret is very important and should be secured appropriately. You will need it in the next phase of the process to request an access token so your application can issue grdAPI commands using REST.

Request an access token

Requesting an access token can be invoked as a REST API request from a valid Guardium user on the system that has the client_secret.

You can use a variety of programming languages depending on your personal preference. For the examples in this article, we used curl to invoke the requests. After the -d option, in the http request body we included all the different GrdAPI parameters required for the OAuth request, as follows.

  • client_id= client_id1, the name of the client that was specified when you registered the client.
  • client_secret= 3ac89782-ce55-4f24-b795-b6c76ecc4045, the client secret that you got when registering this client.
  • username= admin, a valid Guardium portal user that has the permissions to invoke the API functions we want to invoke.
  • password= <password>, the password for Guardium use.

Listing 5 shows how to request the access token and the response. (Line breaks were added due to space constraints.)

Listing 5. Request an access token
Request:
curl -k -X POST -d 
'client_id=client_id1&grant_type=password&
client_secret=3ac89782-ce55-4f24-b795-b6c76ecc4045&username=admin&password=guardium' 
		         https://10.10.9.248:8443/oauth/token
Response:
{"access_token":"80cdcfa3-e02e-4bd6-829a-6b656beaa90a",
  "token_type":"bearer","expires_in":10799,"scope":"read write"}

In the example, the Guardium appliance IP address is 10.10.9.248.

The access token, in bold type in Listing 5, can now be used to verify the authenticity of the remaining REST API requests until it expires. It's important to use this access_token in the header for the grdAPI request, as follows.

"Authorization: Bearer 80cdcfa3-e02e-4bd6-829a-6b656beaa90a "

Using the REST API

This section has examples of using the REST API to invoke Guardium functions. The examples use curl as a web client, but in a real environment an external system will issue the web requests.

  • The authorization token for the request is specified in the header as Authorization:Bearer.
  • The requested operation is specified by one of these HTTP methods: PUT, GET, POST or DELETE.
  • The resource on which the operation is performed is specified on the URL.
  • On GET requests, additional parameters are specified on the URL.
  • On all other requests, additional parameters appear after the -d and are formatted as JSON notation.

Create a datasource (datasource)

Datasources are often used in Guardium for specifying database servers for such things as running classification processes (sometimes called sensitive data finder), security assessments, S-TAP verification processes, and more. This REST API example creates a datasource on the Guardium appliance using the POST action. It is to be associated with security assessments, which are part of the InfoSphere Guardium Vulnerability Assessment offering.

As shown in Listing 6, the command takes parameters such as the application, database server host, database name, owner, password, and so on. Details about the parameters are in the InfoSphere Guardium information center (see Resources) or you can query the restapi resource as described above.

Listing 6. Create a datasource
Request:
curl -k --header "Authorization:Bearer 80cdcfa3-e02e-4bd6-829a-6b656beaa90a" -i -H
	 "Content-Type: application/json" -X POST -d 
'{application:"Security Assessment",host:10.10.9.252,name:"MSSQL252",
	owner:admin,password:"p$ssWOrd",port:1433,shared:true,severity:MED,
		type:"MS SQL SERVER (DataDirect)",user:sa}'
		 https://10.10.9.248:8443/restAPI/datasource
Response: HTTP/1.1 200 OK Set-Cookie: JSESSIONID=8C90021B43CCAF324FD72D498B0D4C93; Path=/; Secure; HttpOnly Content-Type: application/json;charset=ISO-8859-1 Content-Length: 36 Date: Fri, 01 Nov 2013 23:59:38 GMT Server: SQL Guard {"ID":20007,"Message":"ID=20007"}

The response indicates that the datasource was added successfully, and the ID for the datasource is 20007. This ID can be used in subsequent commands to manipulate the datasource because you can use commands that manipulate an object either by its name (description) or by ID.

If a datasource with the same name already exists, an error response will be returned, as in Listing 7.

Listing 7. Error from creating datasource
Response:
{
  "ErrorCode": 102,

  "ErrorMessage": "create_datasource: ERR=102 Error creating Datasource, 
		a Datasource with the specified name already exists. "
}

If an error is preventing the call from executing (a wrong or expired access token, wrong resource, wrong verb), then the HTTP status will indicate such. If the request is executed and produces an error such as missing required parameter, object already exists, wrong parameter value, and so on, then the HTTP status is 200 (OK) and the error indication will appear in the output as a JSON object with ErrorCode and ErrorMessage fields.

Retrieve the datasource (list_datasource_by_id)

To retrieve the datasource we just created, the example uses list by ID, as opposed to list by description, to list the attributes of the datasource created in the previous section. For a GET request the parameters are on the URL, as in Listing 8.

Listing 8. List a datasource
Request:delete_datasource_by_id
curl -k --header "Authorization:Bearer 80cdcfa3-e02e-4bd6-829a-6b656beaa90a" -i -H "Content-Type: application/json" -X GET https://10.10.9.252:8443/restAPI/datasource?id=20007
Response: HTTP/1.1 200 OK Set-Cookie: JSESSIONID=42308503264EAEF37EC1B724DF5F3F40; Path=/; Secure; HttpOnly X-UA-Compatible: IE=edge X-FRAME-OPTIONS: SAMEORIGIN Access-Control-Allow-Methods: POST, GET, PUT, DELETE Access-Control-Allow-Headers: authorization, origin, X-Requested-With, Content-Type, Accept Access-Control-Max-Age: 18000 Content-Type: application/json;charset=UTF-8 Content-Length: 740 Date: Sat, 08 Mar 2014 18:38:58 GMT Server: SQL Guard [ { "DatasourceId": "https://qav9-vm01.guard.swg.usma.ibm.com:8443/restAPI/datasource?id=20000", "DatasourceTypeId": "4", "Name": "MSSQL252", "Description": "null", "Host": "10.10.9.252", "Port": "1433", "ServiceName": "", "UserName": "sa", "Password": "[B@72d272d2", "PasswordStored": "true", "DbName": "null", "LastConnect": "null", "Timestamp": "2014-03-08 13:38:51.0", "ApplicationId": "8", "Shared": "true", "ConProperty": "null", "OsUsername": "null", "DbHomeDir": "null", "CustomUrl": "null", "Severity": "5", "DbDriverId": "4", "CompatibilityMode": "", "DatasourceType": "MS SQL SERVER", "ApplicationType": "SecurityAssessment" } ]

Delete a datasource (delete_datasource_by_id)

As shown in Listing 9, the example uses delete by ID, as opposed to delete by description, to delete the datasource created in the previous section.

Listing 9. Delete a datasource
Request:
curl -k --header "Authorization:Bearer 80cdcfa3-e02e-4bd6-829a-6b656beaa90a" 
-i -H "Content-Type: application/json" -X DELETE -d '{id:20007}'
	 https://10.10.9.248:8443/restAPI/delete_datasource_by_id
Response: HTTP/1.1 200 OK Set-Cookie: JSESSIONID=354039539B475B50EBBFD00892A2F66A; Path=/; Secure; HttpOnly Content-Type: application/json;charset=ISO-8859-1 Content-Length: 36 Date: Sat, 02 Nov 2013 00:09:27 GMT Server: SQL Guard {"ID":20007,"Message":"ID=20007"}

The message {"ID":20007,"Message":"ID=20007"} means that the command executed successfully.

Execute a report and get results (online_report)

InfoSphere Guardium has hundreds of pre-built reports as well as a report building tool to let you create custom reports. In either case, the reports are quite flexible because you can specify parameters at runtime to filter the report output and specify display characteristics, such as how many rows to display on the screen at one time.

To see the report runtime parameters, click the Customize icon, which looks like a blue pencil. This icon is on the report portlet header, as shown in Figure 3.

Figure 3. Accessing the report customizer
pencil icon is highlighted

Figure 4 shows the runtime parameters used to modify the report named AuditTrailSample to narrow by date (NOW-10 days) and to include only those records in which DBUSER is Newuser, no matter which OSUser name is used. The Fetchsize is 20.

Figure 4. Report runtime parameters
text above describes the fields in the customizer.

Figure 5 shows the actual customized report. The contents of the report are not important for this example about the REST APIs.

Figure 5. Example of an InfoSphere Guardium report
example report. actual contents are not important to understanding this article

InfoSphere Guardium now includes a REST API function that emulates the online report functions called online_report. The example specifies a report name (AuditTrailSample), the indexFrom specification, and a list of report parameter specifications such as QUERY_FROM_DATE and QUERY_TO_DATE, and so on. Notice the resource is online_report. This API function returns a set number of result records (default is 20).

You can use the indexFrom parameter for paging, as in Listing 10. If 0 is specified, the first 20 rows of the report are fetched. If 20 is specified, rows 20-39 are fetched, and so on.

Listing 10. Get report results
Request:
curl -k --header "Authorization: Bearer f8839909-5dd9-4cd3-b53e-abe1d4b2d445" 
	-i -H "Content-Type: application/json" -X POST -d 
'{"reportName":"AuditTrailSample","indexFrom":"1","reportParameter":
{"QUERY_FROM_DATE":"2012-12-01","QUERY_TO_DATE":"2013-12-04","OSUser":"%",
"DBUser":"newuser","SHOW_ALIASES":"TRUE","REMOTE_SOURCE":"%"}}' 
	https://10.148.54.136:8443/restAPI/online_report 
Response: HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=65D5D93675858A4E66A7DBDF1B3C21BB; Path=/; Secure; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 6339 Date: Thu, 02 Jan 2014 17:12:40 GMT [ { "Date": "2013-12-03 10:00:00.0", "Instance Id": "7967702005115017", "Session Id": "7967777401785489", "Construct Id": "df2aeb4a38ed9fe51ec043badeab9548b93d3f3f", "Total access": "5868", "Failed Sqls": "0", "DB2 i Current User": "", "Timestamp": "2013-12-03 10:59:59.0", "DB User Name": "newuser", "OS User": "da39a3ee5e6b4b0d3255bfef95601890afd80709", "Source Program": "PORTAL", "Server IP": "10.10.177.111", "Client IP": "10.10.152.179", "Service Name": "SYB30", "Client Host Name": "fd342cd47d2bfa4243d6670c646db6fb0d6347d8", "Server Type": "SYBASE" }, { "Date": "2013-12-03 10:00:00.0", "Instance Id": "7967702005115025", "Session Id": "7967777401785489", "Construct Id": "14a81f3de2e5e3693f9d9cca71e6a50a4d021b00", "Total access": "5320", "Failed Sqls": "0", "DB2 i Current User": "", "Timestamp": "2013-12-03 10:59:47.0", "DB User Name": "newuser", "OS User": "da39a3ee5e6b4b0d3255bfef95601890afd80709", "Source Program": "PORTAL", "Server IP": "10.10.177.111", "Client IP": "10.10.152.179", "Service Name": "SYB30", "Client Host Name": "fd342cd47d2bfa4243d6670c646db6fb0d6347d8", "Server Type": "SYBASE" }, { "Date": "2013-12-03 10:00:00.0", "Instance Id": "7967702005115090", "Session Id": "7967777401785489", "Construct Id": "d621684048e1d5dada7be27db66ed5950722a3e3", "Total access": "6437", "Failed Sqls": "0", "DB2 i Current User": "", "Timestamp": "2013-12-03 10:59:59.0", "DB User Name": "newuser", "OS User": "da39a3ee5e6b4b0d3255bfef95601890afd80709", "Source Program": "PORTAL", "Server IP": "10.10.177.111", "Client IP": "10.10.152.179", "Service Name": "SYB30", "Client Host Name": "fd342cd47d2bfa4243d6670c646db6fb0d6347d8", "Server Type": "SYBASE" }, ….

If the report result is empty, the response looks like the result in Listing 11.

Listing 11. Response when report result is empty
{
  "ID": 0,
  "Message": "ID=0 The Query did not retrieve any records"
}

If the indexFrom parameter specifies a number larger than the number of records in the result, the response is as shown in Listing 12.

Listing 12. Response when indexFrom is greater than records in result
{
  "ID": 0,
  "Message": "ID=0 No More Records Found"
}

Tip: The online_report resource report parameters are different for each report. The restapi resource only specifies a parameter named reportParameter and does not specify the internal parameter structure. One way to find the required report parameters is to look at the customizer screen for that report (see Figure 4). Another way is to invoke the API with an empty reportParameter; the error message in the response specifies the missing parameters, as in Listing 13.

Listing 13. Invoke report with empty reportParameter to discover required report parameters
Request:
curl -k   --header "Authorization: Bearer 1ece8a8a-e60d-47a3-a4f4-d7703bb7c7c9"  
-i -H "Content-Type: application/json" -X POST -d 
'{"reportName":"Guardium Logins","indexFrom":"10","reportParameter":{}}'
	 https://10.10.9.248:8443/restAPI/online_report

Response:
{

  "ErrorCode": 1001,
  "ErrorMessage": "create_online_report: ERR=1001 One or more report parameters missing
	 - QUERY_FROM_DATE,QUERY_TO_DATE,SHOW_ALIASES,REMOTE_SOURCE,HostnameLike"

}

Conclusion

We hope this article has peaked your interest about some of the new REST APIs and that you're thinking about how they might be useful in your environments and solutions. We'd love to hear of any projects using these APIs and any suggestions to further enhance their capabilities.


Acknowledgements

The authors would like to thank Joe DiPietro and John Haldeman for their insightful review comments.

Resources

Learn

Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, or use a product in a cloud environment.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management, Security
ArticleID=968508
ArticleTitle=Using the IBM InfoSphere Guardium REST API
publish-date=04172014