The REST API in Rational Software Architect Design Management 4.0
Overview
Rational Software Architect’s Design Management capability (RSADM) is a Jazz based server application. Its primary API is HTTP REST. RSADM is also an OSLC compliant service provider that is based on linked data principals. The resources RSADM manages are all expressible in RDF.
RSADM is also an Open Services for Lifecycle Collaboration (OSLC) Architecture Management (AM) provider and implements all the required parts of the OSLC specifications. These are considered part of the RSADM ‘public’ API.
RSADM 4.0 is a significant release. It is the first RSADM release to fully support the entire lifecycle management of its resources, including versioning and configurations to support parallel development. Most of these concepts are not yet part of the OSLC specifications. Since the API for operations involving versioning and configurations are not yet defined by the OSLC, we consider these RSADM REST APIs as having ‘partner’ level visibility. That is; the API is available for use, and the RSADM architecture will try to preserve their integrity over time, however it can, and most likely will change as we align with future OSLC specifications that accomplish the same function.
RSADM has another category of APIs: ‘private’ that it uses internally. These APIs, should be considered likely to change over time, and are not intended to be used outside of the RSADM integrated clients and applications. In general when the API requires the special header “x-ibm-rmps-internal: true” then the API is internal, however not all internal APIs require this header. It is best to assume that unless the API is part of the OSLC specification, or has been explicitly documented as public, the API is private.
RSADM 4.0 is the first release that has started to document its REST API with dynamic generation of the documentation based on internal annotations in the source. The advantage of this is the documentation is coming directly from the code that implements the service, and much more likely to be in synch with the current version of the service. The documentation is exactly the right version for the given instance of the running service. Also, documentation is only available for services implemented on the runtime instance of the server. You will not find documentation of services that are not available.
In this initial release of the self documenting API, only a few of the services are completely documented. They can be viewed with the service URL of the form: https://host:port/dm/doc/services, where the host and port are those of the installed and setup server (Figure 1).
Preliminaries
RSADM’s provides an HTTP based REST API. This API follows the IETF RFC 2616 specification, as well as the general spirit of the protocol. Being a Jazz based application RSADM’s authentication comes from the Jazz Foundation Services (JFS). JFS uses OAuth, and all service calls must contain valid OAuth tokens in the session cookies in order to be processed. Web clients get routed automatically to an authentication dialog, and then redirected back to the originally requested web resource. However programmatic clients must be prepared to authenticate, and ‘do the OAuth dance’ before working with RSADM and JFS services. The details of the OAuth protocol, and JFS’s implementation of them are beyond the scope of this article. See the developer works article, ”Add OAuth authentication support to HttpClient” for information about extending the Apache HTTP Client Java libraries for OAuth.
Working with RDF
Many of the resources used in the RSADM API are RDF. Most, but not all, of the services support several representations; RDF/XML, NTriple and Turtle. It is highly recommended that RDF resources be managed with a RDF library like Jena. Jena provides a Java API for reading, writing and processing RDF resources. While it is possible to parse and process RDF resources with other means, using Jena to process resources will guarantee their integrity as well as provide a simple API for access.
Root services document
RSADM being a Jazz based application, relies on a rootservices document. This RDF resource, always located at https://host:port/dm/rootservices lists all the main service end points for the RSADM application, and the Jazz application frameworks on which it is built. This resource does not require authorization. In fact it includes the OAuth authorization URLs necessary to complete the OAuth based authorization process. A client should start with this resource to find and derive the various service end points expected in the RSADM API.
Root services and finding service end points
This example simply GETs the root services document. This document contains the service end points for most of RSADM’s services, and serves as a starting point for all API scenarios.
The root services document is an RDF resource that all Jazz based applications provide, without authorization, to clients wishing to find specific service end points. This document includes OAuth URLs used in the OAuth based authentication process for non-web browser clients.
The root services document can be obtained in the following formats:
- Root services as RDF/XML
- Root services as NTriple
- Root services as Turtle
For example the client GETs the rootservices document passing in an Accept header of text/turtle as shown below.
Request: GET https://example.com:9435/dm/rootservices HTTP/1.1 Headers Accept: text/turtle Response: HTTP/1.1 200 OK Headers Server: Apache-Coyote/1.1 ETag: "nQQLPGLvSXh8NEYQhFJslNFmDkI=" Date: Tue, 11 Sep 2012 15:25:28 GMT Expires: Tue, 11 Sep 2012 15:30:28 GMT Cache-Control: public Content-Type: text/turtle;charset=UTF-8 Transfer-Encoding: chunked @prefix jp: <http://jazz.net/xmlns/prod/jazz/process/1.0/> . @prefix fp: <http://jazz.net/xmlns/prod/jazz/frontingapp/process/1.0/> . @prefix ju: <http://jazz.net/ns/ui#> . @prefix jp06: <http://jazz.net/xmlns/prod/jazz/process/0.6/> . @prefix rh_dist: <http://jazz.net/xmlns/dm/distribute/1.0/> . @prefix oslc_am: <http://open-services.net/ns/am#> . @prefix oslc: <http://open-services.net/ns/core#> . @prefix oslc_rm: <http://open-services.net/xmlns/rm/1.0/> . @prefix rhlocator: <http://jazz.net/xmlns/rh/locator/1.0/> . @prefix vvc: <http://jazz.net/ns/vvc#> . @prefix jtp: <http://jazz.net/xmlns/prod/jazz/jtp/0.6/> . @prefix jdb: <http://jazz.net/xmlns/prod/jazz/dashboard/1.0/> . @prefix dcterms: <http://purl.org/dc/terms/> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix trs: <http://jazz.net/ns/trs#> . @prefix jfs: <http://jazz.net/xmlns/prod/jazz/jfs/1.0/> . @prefix jd: <http://jazz.net/xmlns/prod/jazz/discovery/1.0/> . @prefix rmps: <http://jazz.net/xmlns/rmps/1.0/> . @prefix dc: <http://purl.org/dc/terms/> . <https://example.com:9435/dm/distcenter/baselines> dc:title "Design Management JTS-BaseLines Proxy" . <https://example.com:9435/dm/distcenter/indexing> dc:title "Design Management JTS-Indexing Proxy" . <https://example.com:9435/dm/rhlocator/ld> dc:title "Design Management of Tool's specific Leading Dimensions" . <https://example.com:9435/dm/rhlocator/existingtools> dc:title "Design Management for Existing Tools" . <https://example.com:9435/dm/distcenter/query> dc:title "Design Management JTS-Query Proxy" . <https://example.com:9435/dm/importer> dc:title "Rational Software Architect Import Service" . <https://example.com:9435/dm/rhlocator/locate> dc:title "Design Management" . <https://example.com:9435/dm/rootservices> ju:widgetCatalog <https://example.com:9435/dm/WidgetCatalog> ; vvc:eventReceiver <https://example.com:9435/dm/vvcEventReceiver> ; rh_dist:baselines <https://example.com:9435/dm/distcenter/baselines> ; rh_dist:distcenter <https://example.com:9435/dm/distcenter> ; rh_dist:indexing <https://example.com:9435/dm/distcenter/indexing> ; rh_dist:query <https://example.com:9435/dm/distcenter/query> ; jdb:dashboards <https://example.com:9435/jts/dashboards> ; jd:discovery <https://example.com:9435/dm/discovery> ; jd:friends <https://example.com:9435/dm/friends> ; jd:infocenterRoot <https://example.com:9435/rdmhelp> ; jd:registration <https://example.com:9435/dm/handleSetup> ; jd:viewletServiceRoot <https://example.com:9435/jts> ; jd:viewletWebUIRoot <https://example.com:9435/dm> ; fp:processProxy <https://example.com:9435/dm/processProxy> ; jfs:adminWebUI <https://example.com:9435/dm/admin> ; jfs:baselines <https://example.com:9435/dm/baselines> ; jfs:bulkOperations <https://example.com:9435/dm/bulk> ; jfs:changes <https://example.com:9435/dm/changes> ; jfs:currentUser <https://example.com:9435/jts/whoami> ; jfs:history <https://example.com:9435/dm/history> ; jfs:indexing <https://example.com:9435/dm/indexing> ; jfs:jauthCheckAuthUrl <https://example.com:9435/jts/jauth-check-auth> ; jfs:jauthCheckTokenUrl <https://example.com:9435/jts/jauth-check-token> ; jfs:jauthIssueTokenUrl <https://example.com:9435/jts/jauth-issue-token> ; jfs:jauthProxyUrl <https://example.com:9435/jts/jauth-proxy> ; jfs:jauthRevokeTokenUrl <https://example.com:9435/jts/jauth-revoke-token> ; jfs:jauthSigninUrl <https://example.com:9435/jts/jauth-signin> ; jfs:mailer <https://example.com:9435/jts/mailer> ; jfs:oauthAccessTokenUrl <https://example.com:9435/jts/oauth-access-token> ; jfs:oauthApprovalModuleUrl <https://example.com:9435/jts/_ajax-modules/com.ibm.team.repository.AuthorizeOAuth> ; jfs:oauthDomain "https://example.com:9435/jts,https://example.com:9435/dm" ; jfs:oauthExpireTokenUrl <https://example.com:9435/jts/oauth-expire-token> ; jfs:oauthRealmName "Jazz" ; jfs:oauthRequestConsumerKeyUrl <https://example.com:9435/jts/oauth-request-consumer> ; jfs:oauthRequestTokenUrl <https://example.com:9435/jts/oauth-request-token> ; jfs:oauthUserAuthorizationUrl <https://example.com:9435/jts/oauth-authorize> ; jfs:query <https://example.com:9435/dm/query> ; jfs:search <https://example.com:9435/dm/search> ; jfs:serverRenameStatus <https://example.com:9435/dm/appServerRenameStatus> ; jfs:setupWizardDescriptor <https://example.com:9435/dm/setup-descriptor> ; jfs:storage <https://example.com:9435/dm/storage> ; jfs:users <https://example.com:9435/jts/users> ; jtp:associations <https://example.com:9435/dm/process-authoring/associations> ; jtp:defaultPracticeLibraryUrl <https://example.com:9435/dm/process-authoring/libraries/shared> ; jtp:file <https://example.com:9435/dm/process-authoring/file> ; jtp:license <https://example.com:9435/dm/process-authoring/license> ; jtp:practices <https://example.com:9435/dm/process-authoring/practices> ; jtp:processDescriptions <https://example.com:9435/dm/process-authoring/descriptions> ; jp06:processSecurity <https://example.com:9435/dm/process-security> ; jp06:processTemplates <https://example.com:9435/dm/process/templates> ; jp06:projectAreas <https://example.com:9435/dm/process/project-areas> ; jp:projectAreaInitService <https://example.com:9435/dm/initializationservice> ; rhlocator:existingtools <https://example.com:9435/dm/rhlocator/existingtools> ; rhlocator:ld <https://example.com:9435/dm/rhlocator/ld> ; rhlocator:locate <https://example.com:9435/dm/rhlocator/locate> ; rmps:auth <https://example.com:9435/dm/auth> ; rmps:clmSampleProject <https://example.com:9435/dm/clmSampleProject> ; rmps:comments <https://example.com:9435/dm/comments> ; rmps:compare <https://example.com:9435/dm/compare> ; rmps:compareWithPrevious <https://example.com:9435/dm/compareWithPrevious> ; rmps:design <https://example.com:9435/dm/design> ; rmps:diagrams <https://example.com:9435/dm/diagrams> ; rmps:dm-baselines <https://example.com:9435/dm/dm-baselines> ; rmps:dm-changesets <https://example.com:9435/dm/dm-changesets> ; rmps:dm-history <https://example.com:9435/dm/dm-history> ; rmps:dm-search <https://example.com:9435/dm/dm-search> ; rmps:dm-users <https://example.com:9435/dm/dm-users> ; rmps:dminstall <https://example.com:9435/dm/dminstall> ; rmps:domainRegistry <https://example.com:9435/dm/domainRegistry> ; rmps:dsf <https://example.com:9435/dm/dsf> ; rmps:dsv <https://example.com:9435/dm/dsv> ; rmps:dtkConfigure <https://example.com:9435/dm/dtkConfigure> ; rmps:dtkEditorDef <https://example.com:9435/dm/dtk/EditorDefinition> ; rmps:explorer <https://example.com:9435/dm/explorer> ; rmps:fileUpload <https://example.com:9435/dm/fileUpload> ; rmps:folders <https://example.com:9435/dm/folders> ; rmps:graphLayout <https://example.com:9435/dm/graphLayout> ; rmps:groups <https://example.com:9435/dm/groups> ; rmps:imageInfo <https://example.com:9435/dm/imageInfo> ; rmps:importer <https://example.com:9435/dm/importer> ; rmps:info <https://example.com:9435/dm/info> ; rmps:linkServiceProviders <https://example.com:9435/dm/linkServiceProviders> ; rmps:links <https://example.com:9435/dm/links> ; rmps:linktypes <https://example.com:9435/dm/linktypes> ; rmps:logical <https://example.com:9435/dm/logical> ; rmps:metamodelconverter <https://example.com:9435/dm/metamodelconverter> ; rmps:migration <https://example.com:9435/dm/migration> ; rmps:modelquery <https://example.com:9435/dm/modelquery> ; rmps:models <https://example.com:9435/dm/models> ; rmps:modelvalidation <https://example.com:9435/dm/modelvalidation> ; rmps:oslcquery <https://example.com:9435/dm/oslcquery> ; rmps:owlInput <https://example.com:9435/dm/owlInput> ; rmps:projects <https://example.com:9435/dm/projects> ; rmps:properties <https://example.com:9435/dm/properties> ; rmps:queries <https://example.com:9435/dm/queries> ; rmps:queryvvc <https://example.com:9435/dm/queryvvc> ; rmps:rdfdirectory <https://example.com:9435/dm/rdfdirectory> ; rmps:rendering <https://example.com:9435/dm/rendering> ; rmps:resourceState <https://example.com:9435/dm/resourceState> ; rmps:reviews <https://example.com:9435/dm/reviews> ; rmps:status <https://example.com:9435/dm/status> ; rmps:streams <https://example.com:9435/dm/streams> ; rmps:subscriptions <https://example.com:9435/dm/subscriptions> ; rmps:support <https://example.com:9435/dm/support> ; rmps:trackedResourceSetProvider [ a trs:TrackedResourceSetProvider ; trs:trackedResourceSet <https://example.com:9435/dm/trs> ] ; rmps:transforms <https://example.com:9435/dm/transforms> ; rmps:validation <https://example.com:9435/dm/validation> ; rmps:web <https://example.com:9435/dm/web> ; oslc_am:amServiceProviders <https://example.com:9435/dm/oslc_am> ; oslc:publisher <https://example.com:9435/dm/application-about> ; oslc_rm:rmServiceProviders <https://example.com:9435/dm/oslc_rm> ; dc:title "Design Management"@en . <https://example.com:9435/dm/distcenter> dc:title "Design Management Query and Search Services".
With the root services document you can find the service endpoint for most of DM’s services, as well as services exposed by Jazz Foundation Services (JFS). It is highly recommended that you use an RDF parser to process this document. To find the service end point that you are interested in you must know the property URI of the service. For example to find the DM projects service end point we use the projects service property: http://jazz.net/xmlns/rmps/1.0/projects to find the statement with this property ( rmps:projects ). In this example the projects service URL is ( https://example.com:9435/dm/projects ).
Scenarios
The remainder of this article explains the API with examples.
GETing resource representations
The following examples demonstrate simple resource access. The OSLC representation is a subset of all the internal properties of any DM managed resource. They include some basic properties like title and description, along with links to other OSLC backed resources. Some DM resources are diagram resources. For these it is possible to get an image/* representation of them. The following examples demonstrate simple resource access.
Finding resources with OSLC Simple Query
The client uses the OSLC defined Simple Query service to search for resource matches in a given RSADM project. Each RSADM project has its own query base URL, which scope the query to just the resources in the associated project. The following examples demonstrate first how to find the query end point for a given project, then executing some queries for resources. DM supports both RDF/XML and Atom response formats.
- Obtain Query Base URL
- Query all resources, RDF response
- Query all resources, Atom response
- Query with wildcarded property
- Query for UML Interfaces
- Query for UML Interfaces; include all props
Managing OSLC Links
An OSLC link is, for all practical purposes just a property on a resource that points to another OSLC resource. The property themselves are not part of any of ontologies that define the resources, but rather are a DM managed extension to the resource, and can be put on any resource. RSADM allows links, of any type, from any resource it manages. Following the OSLC guidelines, links are represented as simple RDF properties, and may have properties itself. Creating and removing links from RSADM resource is done by GETing the OSLC representation of a resource, adding the link properties to it, and PUTing it back to the server.
When editing resource in RSADM 4.0 it is important to be aware of the configuration that the changes are being made in. Since the current version of the OSLC specifications do not address configurations, the configuration in which the links are created and removed must be set in the projects properties.
The following examples demonstrate how to use the OSLC representation to create and manage links from DM resources to other OSLC backed resources.
- Find Work Item “Design – Allocate Dividends with Web Service”
- Create an OSLC link from a diagram to a work item
- Remove an OSLC Link
- Find registered link type predicates in a DM project
Creating and editing resources
RSADM 4.0 introduces powerful new configuration management capabilities. All changes to resources must be viewed and made within a configuration context. The configuration URI is required as a query parameter for all changeset operations. Configuration information is obtained from the configuration service. This set of scenarios demonstrates how to create and edit custom resources. The ontology used here come from the DM supplied ‘Examples’ domain. This domain includes an ontology for resources that describe Authors and Books. The scenarios below show how to use changesets to manage the creation and editing of these simple resource types.
- Get Default Configuration URI
- Create new author (implicit changeset)
- Remove resource
- Create new author with batch transaction
- Create new author in a child workspace
Editing RSA UML resources
RSA DM provides a full UML2 ontology, and with the RSA desktop client UML model elements can be created and managed in DM. RSA UML resources managed by RSADM contain a number of properties that are not visible in the OSLC representation. It is still possible to edit these properties, however the API to do so should be considered ‘partner’ level, and not public. This means that while the API is available for use, it may change or be deprecated in the next release.
The following scenario demonstrates how the REST API can be used to make simple changes to the resource’s internal properties.
Summary and Next Steps
The RSADM REST API follows standard HTTP and REST principals. Its official public API is the OSLC AM and OSLC RM specification, however this is limited to managing OSLC links on resources. Full resource management is done in the context of configurations, and requires the use of non-public APIs in RSADM 4.0. This article describes the API through a series of example scenarios.
The Design Management project on jazz.net offers a 60 day trial so you can download and try it out. Additionally the library section on jazz.net contains articles, videos and other resources you may find helpful in learning more.
Copyright © 2012 IBM Corporation
Yes