IBM® WebSphere® Service Registry and Repository implements a subset of XPath 2.0 with extensions to provide a simple yet effective search, query, and create mechanism.
XPath syntax is available through REST, and can be executed from APIs that include SOAP and Service Registry session beans, and the Collection widget in Business Space. This article provides examples of the XPath syntax and shows you how to test XPath using REST. You will also learn how to use REST to create WebSphere Service Registry and Repository objects. The XPath syntax and REST examples can also be used with other APIs, such as Java, SOAP, and the Collection widget in Business Space.
Overview of XPath in the context of WebSphere Service Registry and Repository
XPath is a query language for navigating XML documents. Although the content in WebSphere Service Registry and Repository is not always stored internally as XML files, the contents are modelled as if they were XML, and for the purposes of the examples in this article, you can assume that the data stored in WebSphere Service Registry and Repository is XML or XML-like.
WebSphere Service Registry and Repository provides a governance enablement profile (GEP) that includes the modelled objects and life cycles needed to implement a complete governance process. This article shows you the XPath syntax you need to query and create objects from the GEP. The information is also relevant if you have created a custom profile based on the GEP using WebSphere Service Registry and Repository Studio and added your own modelled objects to it. You do not need a custom profile, and you do not need to install or use WebSphere Service Registry and Repository Studio for this article, but if you have experience of working with a custom profile in UML, it will provide you with useful context and background understanding.
This article assumes that you already have some understanding of Websphere Service Registry and Repository and XPath concepts, and that you are already familiar with the GEP. Examples are given for the WebSphere Service Registry and Repository V7.5 or V8.0 GEP and documentation. The XPath syntax is also supported by earlier product versions, and these examples will work with any GEP version, including V6.3 and V7.0.
Understanding the object model in the context of XPath
The GEP provides a set of concrete types that you can reference directly. For a full list of them, see Concrete types in the Websphere Service Registry and Repository information center. For examples of queries of the concrete types, see information center topics for XPath queries.
Any objects not found in the list of concrete types have a type of GenericObject, both those from the GEP, and any new objects you have introduced in a custom model. The primary type property is used to distinguish between the specific modelled objects of the GenericObject type.
Every object in the model inherits a set of properties implicitly from GenericObject, as well as the properties and relationships from the modelled object and its parents in the inheritance hierarchy. You won't see the implicitly inherited properties in the UML model in WebSphere Service Registry and Repository Studio for these properties:
- name (mandatory)
The bsrURI attribute is an internal unique identifier for objects, and its value is automatically generated when an object is created in WebSphere Service Registry and Repository.
The primary type attribute takes the form
namespace#objectName. The namespace is defined in the object
model, which you can see in WebSphere Service Registry and Repository
under the Stereotypes tab for the package, or in the generated OWL file on
disk. You will also find the primary type as one of the parameters in the
response to a graph query.
Configuring the root URL for REST in WebSphere Service Registry and Repository
WebSphere Service Registry and Repository provides a REST interface than enables lightweight clients that do not support EJBs and web services to perform actions on content and metadata through HTTP requests. In the context of XPath or XML, WebSphere Service Registry and Repository metadata consists of a set of name-value pairs. When you execute a graph query, all of the names and values for an object are returned. With some APIs, you can execute a graph query to further depths and follow relationships to the child objects. In REST, you can execute a query only to a single level. When you execute a property query, you request one or more specific properties by name, and the value for each property is returned.
The examples in this article are provided in two forms: as XPath syntax
(shown in the article), and as links wrapped in a REST heading using a
default root URL. A root URL has the form
http://hostname:port/prefixWSRR/version/. WebSphere Service
Registry and Repository provides two types of query that are appended to
the root URL:
- To retrieve or create content
- To retrieve or create metadata
The examples in this article use the following values:
To use REST syntax in a browser, some characters must be encoded, and the examples in this article have been encoded for you. For more information about special characters, see the information center links in the Resources section at the bottom of the article.
If you have enabled security, the 9080 port will be redirected automatically to an https address with the secure port (the default is 9443). You will also be prompted to log in the first time you execute a query. Use a userid and password with full Administrator access to the WebSphere Service Registry and Repository web UI, such as wasadmin.
(Optional) Setting up WebSphere Service Registry and Repository so that you can use the links in this article
If you set up the following environment, you will be able to click on the links in this article in a browser, making the examples interactive:
- Install a WebSphere Service Registry and Repository V7.5 or V8.0
server on the machine where you are reading this article. Use the
- Default ports (9080 and 9443).
- If you are in an ND environment, deploy WebSphere Service Registry and Repository only on one cell member to ensure that the default prefix (WSRR) is used.
- Load and activate the GEP.
- Load WSDLs and create business capabilities and services. For instructions on these tasks, see the tutorials Governing an existing service and Governing a new service in the in the Websphere Service Registry and Repository information center.
You will now be able to click on the links in this article and execute the XPath syntax as a REST query against your local WebSphere Service Registry and Repository server.
A graph query retrieves all the metadata for an object and the links to its immediate children as relationships. An object that you have created in WebSphere Service Registry and Repository using the WebUI or Business Space is entirely composed of metadata. If you have loaded data, for example a WSDL file or document, you will need a content query to retrieve the contents.
Example 1: Graph query for all objects of type service version
This example retrieves the graphs for objects of type service version. In
the GEP, you create a service version to represent each conceptual
service, and you add relationships from it to one or more WSDL services. A
service version takes the form of a generic object with a primary type of
Example 2: Graph query for a specific named object of type service
A service is automatically created by WebSphere Service Registry and
Repository when you load a WSDL file, and the contents are derived from
the contents of the <wsdl:service> tag in the WSDL file. If you have
completed the GEP tutorial, you will have loaded
AccountCreationDevelopmentEndpoint.wsdl, which holds a
AccountCreationService-Development, which is
used in this example. Here is the syntax to query for all metadata
relating to a specific service, given the name:
If you have completed the GEP tutorial and loaded
AccountCreationDevelopmentEndpoint.wsdl, the response to the
XML graph query from Example 2 will look like this:
Example 3: Property query for name and bsrURI of WSDL documents
A property query retrieves one or more specific properties from an object, which you identify as part of the query. When you query for concrete types, for example a WSDL document, you do not set the primary type. If you have completed the GEP tutorial, you will have loaded several WSDL documents.
The contents do not include the main body of the WSDL file. If you want to see the file contents, use a content query instead, of which there are examples below.
Example 4: Property query for bsrURI of a specific WSDL document using JSON
Now that you have used a graph query to find the names of the WSDL
documents in your system, you can include this information in a query to
find a specific document bsrURI. If you have completed the GEP tutorial,
you will have loaded
EligibilityService.wsdl. The REST
version of this query uses JSON instead of XML. The results are formatted
differently but the content is the same:
For objects that have content, such as WSDL documents, you can retrieve the
content using the bsrURI. You need to identify the bsrURI first, which you
can do using the query from Example 4. A content query has the format
Example 5: Content query for a specific WSDL document
The bsrURI value of an object is unique, so this example is not interactive:
You can also retrieve content using parameters:
If there is more than one matching result for the content query, you will
receive the first match, unless you use the
When you retrieve content, the response is a file. Using REST, your browser will prompt you to save or open it.
Navigating relationships in a graph
XPath uses object relationships to let you navigate to the children of an
object or set of objects. If you executed Example 1 or 2 above, you saw
that a ServiceVersion includes a relationship to an organization named
Example 6: Query for organizations relationship
This example shows a graph query that finds all organizations referenced by one or more service versions, which is not the same as a list of all the organizations configured in WebSphere Service Registry and Repository. If you have completed the GEP tutorial, you will have created three organizations (JKHL Enterprises, Common services, and Commercial), but this query will return only the two that are referenced by service versions (Common services and Commercial):
Example 7: Query for an organization's relationship with a qualified service version
You can use properties to constrain a relationship query. This example finds all the organizations that are referenced by the Eligibility service, and should find only one organization of the three that you created:
Example 8: Query for service versions with parent relationship from an organization
The relationship capability is very powerful: in addition to using relationships to navigate, you can also treat them as search criteria. This example will find all the service versions that have an owner in the Commercial organization:
Searching using regular expressions
Example 9: Query using text matching
You can use regular expressions to create a text matching search against
the contents of a specific property or any property. You can use @* to
match the text against any modelled property, and "i" to use a
case-insensitive search. However, there is a performance impact with
wildcard search, so try to make your search as precise as possible. This
example finds all the WSDL services you loaded for Account Creation and
Eligibility, identified by a namespace containing
Presence and absence searches
Example 10: Query for the presence of a relationship
Example 8 showed how to search for a service version with an owning organization of Commercial. You can also look for the presence of a relationship with any name.
will find all modelled objects with a relationship attribute of
ale63_owningOrganization. However, it will return these
objects regardless of whether the
attribute references an organization or not. If you are using the GEP
unmodified, it will return all objects of type asset or that inherit from
an asset. This will be a long list, and potential types will include
Business Capability, Capability Version, Schema Specification and DOU.
You can make the query more specific if you append the name property, which
ensures that you will only retrieve entities for which the
ale63_owningOrganization value has been set. As always, you
can also filter by primary type or name, and you should do so if you know
the specific modelled object or type you are looking for. This example
shows all service versions that have an owning organization:
Example 11: Query for the absence of a property
You can use null to test for text properties that have not been set, although null is not supported with date or calendar properties. This example shows all service versions that have no consumer identifier set. In the GEP tutorial data, it will find the Eligibility service version but not the Account Creation service version:
Poster Firefox Extension
When you work with REST in a browser, you can only retrieve or query content and metadata. You can create, update, or delete objects in WebSphere Service Registry and Repository using Java, REST, SOAP, or Atom APIs, but you need to develop an application client or use a tool with post capability, such as cURL or Poster Firefox Extension. This section shows you how to use Poster Firefox Extension to create objects using REST. Poster Firefox Extension is available under a BSD license.
The examples were tested using several versions of Firefox starting with V10, and using Poster V3.1.0 on Windows 7 (64-bit). You must install Firefox before you install Poster Firefox Extension. If you have any problems, see the Poster Firefox Extension web site and click on the Issues tab.
Installing and configuring Poster
- Go to the Poster Firefox Extension install page.
- Restart Firefox when prompted.
- The Poster Extension prompt will appear in the lower right-hand corner as a "P" icon. Click it to launch Poster:
Verifying Poster WebSphere Service Registry and Repository configuration
- Enter a target URL with the format
http(s)://[host]:[port]/WSRR/, such as
- If prompted, enter your WebSphere Service Registry and Repository userid and password and click GET:
- If your configuration is correct, a new window opens showing information about your WebSphere Service Registry and Repository server. In this example, the WebSphere Service Registry and Repository server is V7.5,with Fix Pack 2 applied:
Creating objects in WebSphere Service Registry and Repository
Using Poster to create a generic object in WebSphere Service Registry and Repository
- The minimum syntax you need to create a generic object in WebSphere
Service Registry and Repository is the target URL, object type, and
- Click POST:
Using Poster with parameters to create objects in WebSphere Service Registry and Repository
Example 12: Create with empty relationship
- Enter the target URL and object type:
- Enter the parameters in the content pane:
<resources> <resource> <properties> <property name="name" value="Finance"/> <property name="primaryType" value="http://www.ibm.com/xmlns/prod/serviceregistry/v6r3/ALEModel#Organization"/> <property name="ale63_contactEmail" value=""/> <property name="ale63_contact" value=""/> </properties> <relationships> <relationship name="ale63_childOrganizations"/> </relationships> </resource> </resources>
- Click POST:
- A successful response includes the bsrURI of the new object. For
<properties> <property name="bsrURI" value="4ca23f4c-e3fc-4c96.b6ac.ec4676ecac0d"/> </properties>
Example 13: Create with relationship target
This example uses the bsrURI of the Finance organization to set a child of a new IBM organization. It assumes that you have already created the IBM organization and that you know its bsrURI:
- Enter the target URL and object type:
- Enter the parameters in the content pane:
<resources> <resource> <properties> <property name="name" value="IBM"/> <property name="primaryType" value="http://www.ibm.com/xmlns/prod/serviceregistry/v6r3/ALEModel#Organization"/> <property name="ale63_contactEmail" value=""/> <property name="ale63_contact" value=""/> </properties> <relationships> <relationship name="ale63_childOrganizations" targetBsrURI="73e70273-ebb6-46fe.a7d4.6a6f796ad408"/> </relationships> </resource> </resources>
- Click POST.
Example 14: Use a graph query for verification
- To verify that the organizations were created correctly, execute the following graph query in either Poster or a browser:
Hints and tips
- APIs are backwards-compatible but not forward-compatible. For example, V7.5 and earlier API versions are supported by WebSphere Service Registry and Repository V8.
- In XPath, you use the @ prefix for a property, and the (.) suffix for a relationship.
- When you execute a graph query over some APIs, you can query with depth. For example, WebSphere DataPower uses this capability to retrieve both WSDLs and their related mediation policies. However, REST does not allow depth responses, so you will see less content in results in a browser compared to what you will see from some APIs.
- In Poster. you can use either %23 or the # symbol in the content field, but you must use %23 in the URL field.
- You can execute the commands from these examples with the cURL tool instead of using a browser or Poster Firefox Extension.
- If you create objects with security enabled, you can use the secure URL and port (the default is 9443). When you execute queries or retrieve content, the non-secure port (the default is 9080) redirects automatically to the secure port (9443) unless you have disabled the non-secure port in WebSphere Application Server.
- If you execute the same POST twice, then by default you will end up with two identical objects in WebSphere Service Registry and Repository, except that they will have different bsrURIs. You can develop a custom plug-in to prevent duplicates.
- The REST API provides access to commands that can be destructive, so ensure that only users with appropriate access privileges have create, update, and delete authority in WebSphere Service Registry and Repository,
- WebSphere Service Registry and Repository XPath syntax is case-sensitive.
Error handling and diagnosis
Incorrect parameters when creating content
Here are some examples of errors you will see when you try to create an object but don't include all the required properties and relationships.
Incorrect example 1: Create organization with incomplete properties
You must provide mandatory properties when you create a new object. For example, if you use POST to create an object, and provide this URL in Poster Firefox Extension:
The response will contain the following error:
GSR1354E: The property "name" has not been specified in the URL
Incorrect example 2: Create organization with incomplete relationships
You must provide relationship names when you create a new object, even if the content is optional. For example, if you use POST to create an object, and provide this URL in Poster Firefox Extension:
The response will contain the following error:
GSR0018E: Object "posted" is missing the required business model property "ale63_childOrganizations" of type "http://www.ibm.com/xmlns/prod/serviceregistry/v6r3/ALEModel#Organization"
ale63_childOrganizations relationship is optional, which
means that the contents are optional, but you must still specify the
relationship name when you create the organization.
Results not found on retrieve
For a metadata query, if no objects are found that match the query, the
result will be an empty
For a content query with parameters, if no match is found, you will see a server 404 (page not found) error.
For a content query, if the matching bsrURI is not found, you will see this error:
<error> <code>GSR0038E</code> <message>GSR0084E: An error occurred while attempting to lookup item "8b22b18b-4fd0-4007.88a5.3a5d743aa511" in the registry.</message> <causemessage>GSR0597E: An error occurred when accessing the metadata store.</causemessage> <stacktrace>com.ibm.serviceregistry.ServiceRegistryItemLookupException: GSR0084E: An error occurred while attempting to lookup item "8b22b18b-4fd0-4007.88a5.3a5d743aa511" in the registry. com.ibm.sr.athene.access.impl.AtheneAccessImpl.loadObjectByPattern (AtheneAccessImpl.java:1540) com.ibm.sr.athene.access.impl.AtheneAccessImpl.getItemByID (AtheneAccessImpl.java:399) com.ibm.sr.athene.persistence.impl.DocumentAccessor.retrieve (DocumentAccessor.java:109) ...
You must encode characters correctly in a query. For example, if you use
this URL with an unencoded # character in a browser or in Poster Firefox
then the response will contain the error shown below. Note that the query
is truncated after
GovernanceEnablementModel, which is a clue
that the next character (#) is the one that is incorrect:
<error> <code>GSR1350E</code> <message>GSR0089E: An error occurred while dealing with the following query: "/WSRR/GenericObject[@primaryType='http://www.ibm.com/xmlns/prod/ serviceregistry/profile/v6r3/GovernanceEnablementModel" </message> <causemessage>GSR4500E: Error parsing query: /WSRR/GenericObject [@primaryType='http://www.ibm.com/xmlns/prod/serviceregistry/profile /v6r3/GovernanceEnablementModel </causemessage> <stacktrace>com.ibm.serviceregistry.ServiceRegistryQueryException: GSR0089E: An error occurred while dealing with the following query: "/WSRR/GenericObject[@primaryType='http://www.ibm.com/xmlns/prod/ serviceregistry/profile/v6r3/GovernanceEnablementModel" com.ibm.sr.xpath.athene_triplequery.Renderer.parse (Renderer.java:180) com.ibm.sr.xpath.athene_triplequery.Renderer.transformGraphQuery (Renderer.java:120) com.ibm.sr.athene.persistence.impl.QueryManagerImpl.query (QueryManagerImpl.java:145) ...
Ports and security
You must use the correct HTTP type for the port. For example, if you use
the REST query
then the response will contain the following error:
An error occurred during a connection to localhost:9080. SSL received a record that exceeded the maximum permissible length. Error code: ssl_error_rx_record_too_long)
The reverse error will also fail. For example, if you use the REST query
then the response will contain a server connection error, with the exact
message varying depending on which browser you are using.
This article showed you how to compose XPath queries for WSRR and test them using REST. If you have a local WSRR installation with the default configuration, you have been able to test the example queries directly using a browser. You also learned how to use Poster Firefox Extension to create metadata in WSRR, and you have seen examples of how queries can be configured incorrectly, and the errors that result.
The author would like to thank Anna Maciejkowicz (Service Specialist, WSRR Level-3 Service team) and Phil Rowley (Software Developer, WSRR Development team) for their help in reviewing this article.
- WebSphere Service Registry and
Repository information center topics
- WebSphere Service Registry and Repository information
A single Web portal to all WebSphere Service Registry and Repository documentation, with conceptual, task, and reference information to help you install, configure, and use the product.
- Application Programming Interfaces
- Concrete Types from the governance enablement profile
- Configuring access control
- Creating and updating metadata using REST
- Creating content using REST
- Governance Enablement Profile overview
- Retrieving content using query
- REST interface
- Searching and querying
- URL encoding for REST queries
- WebSphere Service Registry and Repository information center
- Other WebSphere Service Registry
and Repository resources
- WebSphere Service Registry and Repository developer resources
Technical resources to help you use WebSphere Service Registry and Repository.
Service Registry and Repository product page
Product descriptions, product news, training information, support information, and more.
- WebSphere Service Registry and Repository requirements
Hardware and software requirements.
- YouTube channel:
WebSphere Service Registry and Repository demos
These short video demos show you how to complete several key service governance tasks using WebSphere Service Registry and Repository.
- WebSphere Service Registry and Repository Information
This wiki provides an alternative portal for quick access to a wide variety of WebSphere Service Registry and Repository resources, and also makes it easy for you to give feedback on the product.
- IBM Redbook: WebSphere Service Registry and Repository
This IBM Redbook discusses the architecture and functions of Service Registry, along with sample integration scenarios that you can use to implement Service Registry in an SOA.
- WebSphere Service Registry and Repository support
A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
An open-source developer tool for interacting with web services and other web resources that lets you make HTTP requests, set the entity body and content type, and inspect the results.
- XPath 2.0
- WebSphere Service Registry and Repository developer resources page
- WebSphere resources
- developerWorks WebSphere developer resources
Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals. Whether you're a beginner, an expert, or somewhere in between, you'll find what you need to build enterprise-scale solutions using the open-standards-based WebSphere software platform.
- developerWorks WebSphere application integration developer
How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application integration and business integration solutions.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
- WebSphere on-demand demos
Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
- WebSphere-related articles on developerWorks
Over 3000 edited and categorized articles on WebSphere and related technologies by top practitioners and consultants inside and outside IBM. Search for what you need.
- developerWorks WebSphere weekly newsletter
The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
- WebSphere-related books from IBM Press
Convenient online ordering through Barnes & Noble.
- WebSphere-related events
Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
- developerWorks WebSphere developer resources
- developerWorks resources
downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
business process management developer resources
BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks tech briefings
Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
- developerWorks podcasts
Listen to interesting and offbeat interviews and discussions with software innovators.
- developerWorks on
Check out recent Twitter messages and URLs.
- IBM Education Assistant
A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
- Trial downloads for IBM software products