Skip to end of metadata
Go to start of metadata

This tutorial is for 1.x version of JRJC project.

Do NOT post comments here - especially code excerpts including your credentials!. Use to post your questions. It's constantly scanned by various people and you will be answered even faster than here.

Creating the project


The easiest way is to use Apache Maven2 for managing your project and just add the following dependency in your pom.xml:

Other build tools

JRJC library has several dependencies you need to have in your classpath in runtime.
See Project Dependencies for details.

Establishing "the connection"

RESTful architecture promotes stateless connection - that is there should be no notion of the user session.
Currently JRJC fully supports only Basic HTTP authentication (other means are coming soon), which means that you should not use it in public networks without encryption as your credentials more or less travel in the open text (just encoded with Base64). Thus use HTTPS to talk to your JIRA whenever possible. Use HTTP only in internal, private networks or for tests.

To talk to JIRA you need to obtain first a reference to object, which then allows you to get references to more specialized parts of the client stack responsible for things like: handling issues, users, issue metadata, projects, etc.

Classes implementing are capable of giving you the reference to objects.
The current only implementation is Jersey-based one:

The following code snippet gets the reference to JiraRestClient

Where to get myAuthenticationHandler. It depends what type of authentcation mechanism you want to use. Currently you can construct an object of class or (for anonymous connection - Alternatively you can use to create JiraRestClient using HTTP Basic auth with a single call.

When you have your JiraRestClient object, it's time to make some use of it:

When things go wrong

Many things may go wrong and they often will. Network problems, authentication problems, bad data, invalid operations attempted, etc. - all of them may fail.
JRJC uses unchecked exceptions (similarly to other successful frameworks like Spring) in such cases. is the exception thrown by JRJC classes. The original exceptions are wrapped by this exception. At the moment you need to use getCause() to find underlying problem (like HTTP error code returned instead of expected 200 or 201) or just retrieve human readable reason with getMessage()

  • No labels


  1. Anonymous

    Hi guys,

    great that you started the REST API and even offer a Java client for it! So far the tutorial code above helped a lot to get started and the code worked with one exception: I couldn't see the "Start Progress" transition (only Close and Resolve were available to me). Do you have an idea why (I use JIRA in version 4.2.1)? How can I assign issues to team members programmatically? Is there any more Java REST client documentation? I checked your code, but you seem to have designed those "transitions" to be relatively future-proof and let the client have more features when the server gets them. However, this makes it difficult to work with the Java client without more documentation.

    Some hints would be appreciated. Keep up the great work!


    1. Hi,

      REST API of JIRA 4.2.x does not support assigning or editing issues. Only workflow transitions (and setting fields for workflow screens) are supported.
      I bet you did not see "Start Progress" because JIRA out of the box allows only the current assignee doing such transition. So you would need to be assigned first to Start Progress. But... assigning is not supported (Catch 22) ... yet. Please watch this space - JIRA 4.3 and subsequent releases will have more and more rich REST API.

      Could you please explain what kind of client documentation you would mostly expect (value)? I cannot commit that I will be able to write it, but it's possible that I will find time to improve bits and pieces.


      1. Anonymous

        Hi Wojtek,

        thank you, yes, you are right. "Start Progress" was not available as I haven't yet assigned an owner to the issue. I did it by hand and then it worked. But without assignment and the like I had to drop REST as an option which is really sad.

        My problem is that I need to access a 4.2 installation (currently) on Android and that's not that simple with SOAP either. JDK 6 WS support can't parse the WSDL of JIRA which is said to be not 100 % compatible (do you know of this?). Even if, Android doesn't contain all javax.xml packages and I would need to repackage the missing ones. AXIS 1.3 is working, but it misses even java.* packages not available for the Dalvik VM so I am out with ksoap2-android only which is not a convenient way to work with the JIRA web services API.

        I hope the REST interface will grow in the future which makes it also simpler to be used with Android which advocates REST over SOAP anyway. So thank you for pushing this API!



        P.S.: About the documentation? Well, at least all what's not directly visible in the concrete Java client API (basically the generic, untyped access methods like the transitions stuff) would benefit from documentation so that a developer doesn't have to probe his way into the API. API that's exposed through classes and methods I can manage with JavaDoc or the sources, but stuff that appears by probing the API is tough and takes time to experiment and learn.

  2. Anonymous


    I'm Eduard and till now I was working with SOAP interface but due to problems with the timetrackingfields I'm investigating alternative methods to extract the information like REST.

    My question is about if is posible to get an issues list through rest-client (like a jql query) ?

    Thank you

    1. JIRA 4.3 (to be released quite soon - (EAP releases are already available) exposes via REST issue list returned for a JQL query.
      I have just started extending this library to consume this new feature.
      I am planning to have it ready by JIRA 4.3 release day.

  3. Anonymous


    I would love to use something like geckoboard, therefore I need to get the number of open issues, close issues, in progress issues etc. 

    Is there any way today to get this via REST api? Is that possible with the SOAP api? Does someone know a java client implementation for that?




    1. JIRA 4.3 (EAP versions already available) expose full JQL capabilities via REST. JRJC on trunk already supports it. I am going to release it together with JIRA 4.3 final.
      Except for that you can use XML-RSS available in JIRA for ages and treat it as REST-like interface which serves the results of any query.

      For examples, this URL:

      gives you in XML all unresolved issues from JRJC project.

      I hope it helps.


  4. In the source code above:

    // This line could benefit from a brief explanation
    final NullProgressMonitor pm = new NullProgressMonitor();

    // Is there any reason why you keep calling getIssueClient() instead of just calling it once, which might help to make the code more compact?
    final Issue issue = restClient.getIssueClient().getIssue("TST-1  ", pm);

    // It would also be helpful to have error handling in this example code, since this is always one of the more painful points of using remote APIs

    p.s. This page could also benefit from some grammar checking and there's a typo in createWithBasicHttpAutentication

    1. Thanks Matt,

      I'll update the sample code at the time I will be releasing JRJC 0.2.
      WRT grammar: feel free to point/list such mistakes. I am not the native speaker. I am all for learning and improving my English.
      Our tech writers are quite busy and it's extremely difficult to get their cycles for a free and open source project like JRJC.


      1. Better than my Polish! This is a great resource for the future of REST in JIRA.


  5. Anonymous


    Sorry, I am new to Maven and do not understand the above step. How do you create a Maven project? Which archetype do you choose and what should be the pom.xml entries? can someone share their project?

    1. Hi,

      I recommend following this tutorial.
      Just include jira-rest-java-client in your <dependencies> section and it should work.
      The archetype depends on what kind of application you write (jar, war, etc.)


      1. Anonymous

        Thanks Wojtek. I followed the steps and successfully ran the example.

        Just wondering if there is any API method to get all the projects that the user can see in JIRA.

        Iterable<BasicProject> projectListForUser = projectClient.getAllProjects(pm);

         This is not present in current API list. Can someone suggest?

         Or how to use the JQL search using REST API?

        1. Getting all projects and JQL search are only supported by JIRA 4.3 and newly released JRJC 0.2 (not 0.1). Just bump up your dependency on JRJC from 0.1 (or 0.1.1) to 0.2 and you should see API for these new methods.


          1. Anonymous

            The problem is that I have a stand alone JIRA version 4.2.4 and the organization has Enterprise Edition, Version: 3.13.1-#33

            I cannot modify the versions. Is there any other work around?

            Also just wanted to check, will REST Client be supported on the current version in the organization?

            sorry for the trouble.

            1. JIRA 3.13.x does not expose any REST API whatsoever. The client you use won't change it. So either you have to use SOAP or XML-RPC there or create your own server-side plugin which adds remote API capabilities (unfortunately for JIRA 3.13.x it's not as simple as for JIRA 4.x).
              JIRA 4.2.4 does not support querying via REST for all projects. So JRJC won't help you here. JRJC is the client library - it can only do as much (and not more) as the server offers.
              Adding your own REST resources is quite simple with Atlassian plugin framework though. If upgrading from JIRA 4.2.4 to JIRA 4.3 is out of question for you, then take a look at

              1. Anonymous

                Thanks for all the help. I have already created my own plugin for JIRA and tested that too. If I have to access JIRA data from my own plugin (which is running successfully for helloworld) what should I do?

                I cannot access the underlying database directly from my plugin. The whole point in using JRJC was that I did not have to touch the db and could get data from JIRA itself.

                From my own plugin module, can u suggest how I can get suppose, say projects and filters for a particular user and issues for any selected project?

                1. Hi,

                  So your question now completely drifted from JRJC to a general ground of JIRA plugin writing.
                  I recommend reading some tutorials from (especially this one which shows how to search for issues).
                  To get the projects and issues for any selected project you can inject ProjectManager (e.g. getProjectObjByKey()) and SearchProvider to your Java class.

                  Please ask any further questions related to JIRA plugin development (server-side) at JIRA Development Forum.


  6. Anonymous


    I'm trying execute the example, but I got this exception:

    Exception in thread "main" java.lang.NoSuchMethodError: com.sun.jersey.client.apache.ApacheHttpClientHandler.<init>(Lorg/apache/commons/httpclient/HttpClient;Lcom/sun/jersey/api/client/config/ClientConfig;)V at at<init>( at at at Consulta.main(
    Exception in thread "main" java.lang.NoSuchMethodError: com.sun.jersey.client.apache.ApacheHttpClientHandler.<init>(Lorg/apache/commons/httpclient/HttpClient;Lcom/sun/jersey/api/client/config/ClientConfig;)V

    I put all mandatory dependencies

    It's the code

    JerseyJiraRestClientFactory factory = new JerseyJiraRestClientFactory();

    URI jiraServerUri = new URI("http://somejiraserver/");

    JiraRestClient restClient = factory.createWithBasicHttpAuthentication(jiraServerUri,user, pass);

    Can anybody help me, please?


    1. Unknown User (mezga)


      I had the same error with  jrjc 0.2-m1.

      I could avoid with jersey 1.6 (instead of written on dependencies page).

      Good luck,


      1. I still get the same error after upgrading to jersey 1.6. Can you share the list of libraries you have and their versions? Thanks!

        I'm using jrjc 0.3-m1.

  7. Anonymous

    I don't see a way to create an Issue using this library. I suppose it's not supported yet. What's the plan about this?

    (can't login to this website - "login" link does not work)

    1. This is sad, but it's true: JIRA REST API does not allow (yet) to create an issue via REST. So neither JRJC can do it.
      Issue creation is however on a short-term roadmap for JIRA.
      We know it's important and an obvious missing piece of API.
      As soon as JIRA supports it, JRJC will support it too.

  8. Unknown User (mezga)


    Is there any plan to integrate cookie based authentication into JRJC? If yes when?
    Any hint how to use it now in JRJC?



    1. Yes (and SAL too), I have even implemented some initial parts of it. However it's not yet completely done.
      Stay tuned.

  9. how can I know the differences between the library versions? e.g. between 0.2 and 0.2.1

    1. Hi,

      Take a look at the list of fixed issues in 0.2.1 in JIRA (here 1 issue only BTW).
      For bug-fix releases I don't write separate release notes.
      For major version I will.


  10. Anonymous


    This example uses BasicHttpAuthenticationHandler. Is there a way to connect via HTTPS ?

    Our Jira URL is "https://.."

    so I am unable to run this example. Is there currently no way to connect with an https url?

    1. Anonymous

      hi, i face the same problem. Did you solve this?

      1. Hey, if you connect via HTTPS to the server which has normal certificate (signed by approved CA), then it should work without any issue.
        If you use self-signed certificates on your server, then you would have to configure HttpClient (used by JRJC) to accept such certificates. JRJC uses version 4 of this Apache library.
        There should be articles available online which explain how to configure HttpClient to work with such certificates.

  11. Anonymous

    I am using JRJC library and want to get the subversion commits, history and comments for a given issue. I was looked at the Issue interface but was not able to find the method that performs the above service. Thanks.

    1. Hi,

      Subversion commits are not in the scope of REST API provided by JIRA (core) itself. Subversion integration is achieved by JIRA Subversion Plugin or by FishEye. In case you use the latter, you can use FishEye remote API to achieve what you want (you can search for all commits related to given issue).
      WRT issue History - it's not served by REST API - I've raised issue for that.

      Now regarding comments - do you mean normal JIRA issue comments or Subversion comments related to an issue? If the former, then REST does serve such info (see, if the latter, then using FishEye REST API would be an answer.


      1. Anonymous

        Thanks for your comments. I will provide the context for my query. I am a researcher and investigating techniques to predict the source-code file that will be modified/impacted for a given bug report (bug localization) and hence want to create an experimental dataset of bug ids, bug title/description etc and the associated files that were modified.

        I can parse the html source and extract the revision ids using pattern-recognition/regular expressions. I just wanted to validate if this is the best approach for my requirements. Thanks.

  12. Anonymous

    I am not able to retrieve the description for an issue using JRJC library (jira-rest-java-client-0.3-m1.jar) as the method issue.getDescription() is undefined. Please

    1. Hi, I am not sure what you really mean. Could you raise a bug at with more details?


  13. Unknown User (buzzterrier)

    We are using Crowd as our SSO solution. How do we pass a crowd token to the AuthenticationHandler?

    1. JRJC does not support yet cookie-based session/authentication.
      I am going to work on it in the near future though.

  14. Unknown User (mezga)


    is there any reason why I cannot get "self" from rest Attachement object?

    in jrjc 0.3.1


    1. No reason I guess - that's a stupid bug/omission.
      Just wonder - what would you like to use this URI for? The content URL is available with Attachment.getContentUri().

      I've raised the bug as and I've just committed the fix (trivial) to trunk. Feel free to checkout trunk and compile JRJC for yourself - it should be stable against JIRA 4.2-4.4 and in flux for 5.0

      1. Unknown User (mezga)

        Thanks, for the answer Wojtek.

        Yes, I use getContentUri() instead.

        I just did not know what mistic details can be in the background behind this getSelf() method :-)

  15. Anonymous

    Hi guys!

    So that means that if we are using a https://... then we can't connect to JIRA using JRJC?

    1. well, it works for me (I've checked against a few instances). Do you perhaps use some self-signed certificates or client-side-certificates?

      1. Anonymous

        Everytime we try to access JIRA using google chrome or other browsers, they always say that security certificate is not trusted. We just click okay to access it. Is that the client-side-certificate you're asking? What does it have to do with using JRJC?

  16. Anonymous

    Hi there! I downloaded the jar file and included it in my java project in eclipse. I just right clicked build path and added it as an external jar. After that i created a class "Example1" so i can just copy and paste the sample code above. I added the code "import com.atlassian.*;" to include all of the classes but it didn't work. It says "cannot resolve to a type". What might be the problem and possible solution?


  17. Anonymous

    hi. i would like to ask if there is something wrong with my code. i just modified the Example1 code above to just vote on the issue. here is my code. kindly check it out and see what i do wrong. i still get a java.lang.ClassNotFoundException when i run my code.

    1. Hi,

      import statements won't help you if you don't have needed classes in your classpath. Getting ClassNotFoundException thrown usually means that you miss a required jar in your classpath. JRJC uses several external libraries (e.g. for HTTP and JSON manipulation) - you need to include them all in your CLASSPATH (carefully observing versions).
      Take a look at Project Dependencies.


  18. when do you expect to add "estimated time" info to issues? this is a very important part of the API for me.

    1. Hi,

      If you mean the ability to get estimated time info - that's already supported. and there you have all three time tracking values. (logged, original estimate, remaining estimate).

      If you mean setting/editing this value -> then JIRA REST API in 4.4.x does not support it. It will be available only in 5.0. Once it's available, JRJC will get this capability too.


      1. Ahhh... I see. it's in the NEW docs:

        I was reading the old 0.2 version  docs, which are still referenced from

        1. Thanks. I forgot to bump up the link to the newest javadoc. Now fixed.

          1. No worries. Thank you, Wojtek. We will integrate the last library into our application (Task Adapter - it's a software to integrate Jira and Microsoft Project). Looks like the library provides all the basic info we need to LOAD from Jira.

            We'll have to use our old SOAP-based library to SAVE data to Jira, though - until your library provides all that functionality.

            Thanks a lot!

  19. Anonymous

    I meet a problem when I use the example in the above section. However, when i run the code, the debugger always shows that 

    java.lang.ClassNotFoundException: com.sun.jersey.client.apache.config.ApacheHttpClientConfig

    So, where can i get this class to avoid this problem?


    1. Hi,

      it looks like you are missing some jars in your Java classpath. To help you, I need more details about your build system or dependencies you use.
      Feel free to raise an issue in JRJC project here and then we can have more discussion there.


  20. Anonymous

    Is there any reason why the JsonFieldParser class doesn't parse a "com.atlassian.jira.plugin.system.customfieldtypes:userpicker" into a BasicUser at the very minimum for an IssueRestClient request? If not is there a roadmap to try and map out some of the custom field types like that more in the REST client?

    1. That's a very good point. I simply had no time to implement it yet.
      I've added it to JRJC backlog:

      Stay tuned, I am going to spend some time on JRJC in near future so a new version is definitely expected.

  21. Anonymous

    I badly needed resolution date to be included in the Issue data that is returned from the REST client for a project that I'm working on. In the latest code from svn trunk (0.5-SNAPSHOT) I've modified domain/, internal/json/, internal/json/ to provide the data. Is there some place I can provide a patch?

  22. Anonymous

    Does JRJC support HTTPS?  Do we have any example?

    1. If your HTTPS server uses regular SSL certificate (signed by thrusted CA), then you don't need to do anything special. Just use the sample code, but specify URI using https and that should work.
      If your server uses self-signed SSL certificates, then you would need to configure Apache HTTP Client (which JRJC uses) to accept such certificates. I don't have sample code for you at the moment, but I think I need prepare it one day as several people have already asked for it.

      1. Anonymous

        I have the .cer files and plan to import it to a keystore.  How do i have JRJC pick up the certificate from the keystore?

        1. If you import the certificate into the standard keystore used by Java, then you don't need to do anything else. JRJC will transparently pick up this cert (actually Java will seamlessly handle it in its SSL support).
          Detailed info on how to import a certificate into a keystore or how to tell Java to use different keystore is available for example at:

  23. Anonymous

    Any reason I shouldn't use JRJC for my production?

    1. Just the contrary. Feel free to use in your production environment. I don't know about any reason not to use it.
      JRJC currently supports JIRA 4.2 - 4.4.x and full compatibility with incoming JIRA 5.0 is coming soon.

      1. Anonymous

        Thanks Wojtek.

  24. Anonymous

    How do i get total time spent on a version and a split by the resources?

    How do i get all the issues on a version?



    1. JIRA REST API does not expose such info directly (wrt total time spent on a version).
      Instead you can use JQL query (offered by SearchRestClient), search for all issues from given version and finally retrieve details of all issues matching this query and sum up the total time spent on the client side.
      Unfortunately it will need N + 1 remote calls, which may be unacceptable if you thousands of issues match your query.
      In JIRA 5.0 REST API has better support for JQL queries returning inline more info which you need.
      But that's not yet implemented in JRJC, although I hope it will soon be.

      1. Anonymous

        Thanks Wojtek.

        Version has other details like start date and end date.  How do i get those version attributes?



        1. VersionRestClient.getVersion() should be used to retrieve all available details of given version - like release date, whether version is archived, released, its description.
          Start and end dates though are the concepts introduced only by GreenHopper and they are NOT served by REST API with standard version information. Actually that's because start and end dates are not added to JIRA core model (it's not extensible) but rather these are separate things just hooked in into GreenHopper UI where versions are manipulated.

  25. Anonymous

    Hi, i resolve all jar dependences, but i get this error, anyone got similar error???

    30-01-2012 08:09:00 PM com.sun.jersey.api.client.ClientResponse getEntity
    GRAVE: A message body reader for Java class org.codehaus.jettison.json.JSONObject, and Java type class org.codehaus.jettison.json.JSONObject, and MIME media type application/json;charset="UTF-8" was not found
    30-01-2012 08:09:00 PM com.sun.jersey.api.client.ClientResponse getEntity
    GRAVE: The registered message body readers compatible with the MIME media type are:
    / ->

    Exception in thread "main" com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class org.codehaus.jettison.json.JSONObject, and Java type class org.codehaus.jettison.json.JSONObject, and MIME media type application/json;charset="UTF-8" was not found

    1. I get those errors sometimes too. I usually end up getting the contents from a URL as a String and then using 

      JSONObject json = new JSONObject(str);

      I dug into the reason for the error a year or two ago and it seemed to be about the message body reader class not being loaded by the plugin class loader or bundled with the plugin. Total pain to track down.


  26. Anonymous

    It's possible to create an issue via rest client ??

    1. JIRA REST API up to 5.0 (final version coming very soon, RC versions available) does not support creating issues.
      In 5.0 it's supported. However current version of JRJC does not support yet these new features of 5.0. However it's planned in next several weeks to make JRJC consume everything new shiny REST API of 5.0 really offers.

  27. Hi Wojtek,  I'm trying to wedge it into integration tests, any thoughts on integration testing using this client?  Id like to use it for data retrieval but the jersey requirements (jersey-1.5) seem to conflict with jira-func-tests(5.0-rc2) which pulls in jersey-core (1.0.3) :( Is jira-func-tests going to get updated at some point?

    1. Hey, We have been successfully using JRJC in integration tests in our plugins (which also depend on jira-func-tests). You have to just make sure that your jersey libs have higher priority than dependencies from jira-func-tests, which usually means you have to include dependencies explicitly in your pom.xml. Take a look at JIRA Importer Plugin which uses both JRJC and jira-func-tests (both worlds are even mixed in a single test class IIRC).

      Excerpt from JIM:

      1. That's good info. The jersey-1.0.2-atlassian thing bites me quite often.

      2. OK, thanks, will try.  Meantime I've jury rigged some basic JSON parsing the rest response, pretty basic - the client would be a better solution, when I get some time!