API Check: Diagnostic Application for WCI's API Service

By
bill
on February 11, 2009 11:50 AM | | Comments (1)

Unfortunately, WCI ships without providing an easy way to validate that the API service works properly. Some system administrators mistakenly believe the API service works if they see the message "Hi there, this is an AXIS service!" That message only confirms the service has been turned on and gives no information about whether it may have fatally failed at startup. To provide real health information for the API service, I've written the API Check application.

This application was tested on ALUI 6.1 and WCI 10gR3.

Contexts for Use

Portal administrators will most likely choose to run the API Check application within the WCI portal as a portlet. Portlet mode is always available when the API Check application is turned on. Some organizations will additionally wish to access the API Check application available outside the portal through its standalone mode. Standalone mode is most useful when the organization performs automated service monitoring such as for a load balancer and needs to see the status without logging into the portal.

Risks

In portlet mode, this application presents no security risks. The application will retrieve a login token from the portal's request allowing API Check to connect to the system as the calling user. This is the recommended approach. However, in standalone mode, there is a security risk because standalone mode requires a credential for a portal user be stored within the applications's web.xml file. This should be avoided when possible. If however you do choose to enable standalone mode, then be sure to use the credentials of a user with minimal rights to the portal. No special priviledges need be given to this account, and the account certainly should not have any administrative rights. The automated monitoring should scan for "DBQuerySuccess" to determine the service is up.

Install

This application runs adjacent to your existing %WCI_HOME%\ptws\10.3.0\webapp\ptapi.war file so that it will start and stop as the API service starts and stops. To install:
  • Place apicheck.war into the API service's webapps directory.
  • Import apicheck.pte into your portal. That PTE file is located within apicheck.war's install-resources directory. You can get there via http://localhost:11905/apicheck/install-resources/APICheck.pte (using an appropriate host). The PTE file will create an administrative folder, a community, a remote server, a web service, and a portlet for the API Check application.
  • From the portal admin interface, edit the API Check remote server to go to the proper address.
  • Browse to the API Check community to verify the portlet works.

Optionally, follow these additional steps if you wish to use the standalone mode:

  • Make sure you have the credentials for a portal-based user with low privileges in the portal.
  • Unpack apicheck.war
  • Edit WEB-INF\web.xml such that the values for username and userpass represent the low-rights account that should connect
  • Repack apicheck.war with the new web.xml file
  • Restart the API service
  • Browse to http://localhost:11905/apicheck/index.jsp to validate that it works.

Get the Code

This application is available for download here.

Note: The code was updated on March 20 09 to test the search API with a lookup of communities (fast) instead of users (potentially slow). Read more.

Enjoy!
API Check in Portlet Mode

 

API Check in Standalone Mode

Categories:

Tags:

1 Comments

By joel on February 11, 2009 8:20 PM

this is great stuff. the WCI community needs more useful tools like this. I'd recommend adding it to something like the ALUI-toolkit on google code or some other central source that people can more easily find.

Leave a comment