JIRA JSON-RPC Overview
Starting with JIRA 4.4. there is a new remote JSON-RPC API capability.
The future of remote APIs in JIRA lies with REST. However, until these APIs are fully built out, up to now the only option was to use the SOAP APIs.
SOAP messaging is unfriendly to many developers, especially those wanting to make calls to JIRA in a browser AJAX environment.
The code uses the Java server code that makes up the existing SOAP interface in JIRA. There is a one-to-one mapping between the methods and parameters in the JIRA SOAP API and the equivalent JSON-RPC methods and parameters.
The main difference is the JSON-RPC wire format.
How the API is Implemented
The JSON-RPC API is provided by an open source plugin that is bundled with JIRA 4.4 and later. You can find it here on BitBucket.
The plugin uses the code that provides SOAP methods and converts them to JSON-RPC methods. It uses Jackson as the JSON library to provide the mapping between a Java method and JSON-RPC invocation of that method.
The code was originally written as a Confluence plugin and then ported to a JIRA plugin. The mechanism works in both products in very similar manner.
The SOAP calls are made as a POST on the following path:
The JSON-RPC calls are made as POST on this path:
Responses are delivered as MIME type
application/json. Your requests should be too, but that is not enforced by the plugin.
As mentioned above, there is a one-for-one mapping between a SOAP method call and a JSON-RPC method call. For example, the Javadoc for the JIRA SOAP API shows this getServerInfo() method.
where RemoteServerInfo is defined as this:
To make the same call via JSON-RPC, you need to fire the following POST request onto:
Let's have a look at the structure of the JSON-RPC message. It follows the JSON-RPC specification format.
Required. Must have the value "2.0".
Specifies the method to call.
An array of parameters to be passed to the method. In this case the string "l632EGg4Kc" is a security token which we will discuss later.
A unique request ID of your choosing. It will be echoed back to you so that you can marry requests with response. This is particularly useful if you use an asynchronous fire and forget programming technique.
The response contains the echoed request "id" property and a "result" property that is a JSON object mapping of the RemoteServerInfo object. It maps the public methods of the object into JSON properties.
You must use the HTTP POST verb. You cannot use GET to invoke JSON-RPC methods.
The Light Protocol
The plugin also supports a 'light' protocol that allows clients to encode the method name in the URL, and provide only the method arguments in the request body. Non-error responses in the light protocol also omit the RPC envelope and only provide what would normally be the 'result' object in a regular JSON-RPC response.
Error responses are returned as they would under the heavy protocol.
Thus the equivalent to the above request in the light protocol would be as follows.
Remember the method name now goes into the URL and not the POST body.
The POST data is:
It's up to you whether you want to use the full or the light JSON-RPC format.
One advantage of the light format is that access logs will contain the method invoked because it is in the URL. The heavy format will not, because the method is inside the POST data.
You must authenticate with JIRA in order to make SOAP or JSON-RPC API calls. There is a login method that takes a username and password:
which maps to a JSON-RPC message as follows:
This will return an authentication token string that you provide to every other subsequent method call:
If the password is incorrect then you will get a JSON-RPC error message back:
In reality, the data portion of the above example is a full Java stack trace (which like all stack traces is pretty long) and hence in this example I have cut it down using the ... characters.
The same sort of error will occur if the token expires:
There is a logout method which will invalidate the authorisation token and hence prevent it being used for further method calls.
Authentication via another Mechanism
If you have established a JIRA session by some other means (for example you are running in the browser and the user has already logged in) then the token parameter is not checked.
It is still required in the method signature but it will not be validated and hence it can be any value. Remember that browsers keep the user's JIRA session by propagating the JSESSIONID cookie that JIRA sets.
Command line scripts via wget or curl, for example, do not typically keep the user's session. You will need to propagate JSESSIONID if you want to use an alternative authentication mechanism.
The methods available to the JSON-RPC API are all the methods defined in the JIRA SOAP API Javadoc.
You must translate from the Java structure into JSON objects. Use the normal JavaBean rules for translating from one into the other.