This post is about what is available as API for RTC. I will try to provide you with some information about the available API’s. It was confusing to me in the beginning, so I assume others face the same problem.
This post assumes you already read the post about Setting up Rational Team Concert for API Development. Learning to Fly contains references to the most important posts for beginners. Please also consider to look into the Interesting Links page for more examples and downloads.
The first API’s are only mentioned for completeness. They are not covered in this series of posts, but might be in the future.
REST and OSLC APIs
RTC provides some REST API’s that can be used to access and manipulate data. It also provides OSLC based APIs to access some of its data. See Using Perl to access the JAZZ REST API as an entry point. This blog post provides you with a different browser extension to use for creating REST and OSLC URL’s
Available Java APIs
There are really two Java API’s available in RTC, and although they have much in common, there are differences that are important to understand if you want to use them. The following API’s are available
- The Server API that is used in the server part of RTC (and JTS)
- The Client API that is used by the Eclipse Client and the Plain Java Client Libraries
RTC Server API
The RTC Server API is used in extensions to RTC that are deployed on the server. Examples for these kind of extensions are Operation Advisors, Operation Participants, Server Tasks and other extensions that are run on the server. The RTC Server API is shipped with the RTC SDK that you set up to have an environment for development. This API is typically found in packages called com.ibm.team.*.service and the interfaces are usually named *Service or *Server for example IWorkItemServer.
This blog has several examples for how to extend RTC using the server API. For example
- Resolve Parent If All Children Are Resolved Participant
- A Create Approval Work Item Save Participant
- Only Owner Can Close WorkItem Advisor
- Do not Modify the Triggering Element in an OperationAdvisor
- The RTC WorkItem Server Link API – Linking to Work Items and Other Elements
- Restrict Delivery of Changesets Associated to Wrong Work Item Types Advisor
- RTC Update Parent Duration Estimation and Effort Participant
RTC Common API
Parts of the API are available on the client and on the server. The way you get the API depends on if you have a client or a server extension, however, the services are available as client libraries as well as as services. This API is typically found in packages called com.ibm.team.*.common and the interfaces are usually named *Common for example IWorkItemCommon. In some cases the required services are provided by the extension mechanism. This allows to write some extensions that run on the server, as well as on the client. A good example are Attribute Customization providers. You can find examples in these posts
- Attribute Customization – Java Based Value Providers, Conditions and Validators
- A Custom Condition to Make Attributes Required or Read-Only by Role
RTC Client API
The RTC Client API is used in Extensions to any of the Eclipse based RTC clients as well as in the RTC Plain Java Client Libraries. This API is typically found in packages called com.ibm.team.*.client and the interfaces are usually named *Client for example IWorkItemClient. The RTC Client API is shipped with the RTC SDK and partially shipped with the Plain Java Client Libraries.
What? The Client API is shipped twice? Why would anyone do that?
RTC Client API
The reason for shipping the client API in the RTC SDK and the Plain Java Client Libraries is really simple. You need it in the SDK to develop extensions for the Eclipse based RTC clients. The SDK provides you with the source code and allows to search the code in the Eclipse Plugin Development Environment PDE. Strictly speaking, you would not need the source code to develop the extensions, because the Eclipse client has the relevant parts of the API already installed as plug in’s and that is enough to be able to write extensions. However, it makes development so much easier. The RTC (client) SDK also ships some internal classes and tests that you can use to find examples for the API usage.
Plain Java Client Libraries
If you just want to run a small Java application to do some automation outside of the Eclipse client, you would need only the JAR files for the API, and some JAR files that it depends upon. It would be quite some effort to identify the JAR files in the Eclipse client you need. So the Plain Java Client Libraries has the required JAR files bundled for you to use. This makes setting up a Plain Java Client application you developed much easier.
The Plain Java Client Libraries ship only the documented and public API. They are missing a lot of RTC Eclipse client specific code.
The post A RTC WorkItem Command Line Version 2 provides an extensive example for using the API to create and modify work items.
Extending Eclipse based Clients
When mentioning you can develop Extensions to the Eclipse based RTC Clients, that was no typo. The Jazz SCM Command Line as well as the Jazz Build Engine and Toolkit are also Eclipse based clients that can be extended. You can find an example for extending the Jazz Build Toolkit in this post from Robin. The Eclipse Extension mechanism works for all Eclipse based clients.
There are several posts on this blog that talk about the client API. For Example
- Uploading Attachments to Work Items
- Manipulating Work Item Enumeration Values
- Working with Work Item Attributes
- Adding Approvals to Work Items Using the Plain Java Client Libraries
- The RTC WorkItem Client Link API – Linking to Work Items and Other Elements
- Changing the Jazz User ID Using the RTC Plain Java Client Libraries
- Analyzing a Project Areas Members and Roles Using The Plain Java Client Libraries
- Maintaining User Photos With the Plain Java Client Libraries
- Jazz.net Article on writing Operation Advisors
What is the Difference Between Client And Server API
Although you can often reuse the client API some things are different in the client and the server API so you need to be careful. The Services and Client Libraries have differences in how they are called and what they provide. Creating, getting and manipulating elements is sometimes slightly different in both API’s and you might need data on the server that you don’t have on the client and the other way round.
What can you Extend and Access?
The Server API allows to extend
- The RTC Server with operational behavior, event handling, jobs and the like.
The Client API allows to extend
- The Jazz Build Engine and the Build System Toolkit
- The SCM Command Line
- The RTC Eclipse client
- Potentially any other Eclipse based client
The Client API allows you to access
- The RTC server and the data in its repository
- Parts of the JTS server, for example the User and License management
What can’t you extend?
As far as I know you can not extend the Visual Studio Client, nor the Windows Shell, because both are not Eclipse based.
The available Extension Points and Operation ID’s are explained here.
Why is the API Designed the Way it is?
If you start working against the API, you will realize that, from a human perspective, sometimes things appear overly complicated. For example if you work with enumerations, you need to look up all the literals to find one that has the same Label value as your string you want to use to set it.
My personal view on this is, the API is a byproduct of what needed to be developed to design clients and servers. In the client for example, you will typically have views, that need to show more than one element. Or you have drop down boxes to select enumeration values. This just requires to get at all the data such as literals, project areas etc. needed to be displayed in that context. There is just no need to be able to provide a method that takes some string and looks up an item that has a display value that matches that string.
If you want it to be easier, you can always wrap pieces of code up to better fulfill your requirements and reuse that code.
Don’t Mix Client and Server API
You need to be really careful, to understand what client API is and what server API. Client API usually has client in the package name and you get the services with getClientLibrary() calls. Server code usually has server in the package name and you get services using gerService() from the AbstractService type you extend.
There are some packages with common in the package name, and contain common code that can be used on client and server. Still, you would get the common classes using getService() on the Server and the analogous Client Library with getClientLibrary() on the client.
If you mix the Client and the Server API in a server extension, you might find it works in Jetty – because that potentially has the client and the server part available in the SDK. But once you deploy the extension on the server it will not load because it can’t find the required bundles. The same applies for client extensions.