Which Java API to use?

I am developing a company application using JIRA as the backend workflow engine. I found 3 Java APIs (we are a Java shop)

  1. https://docs.atlassian.com/jira-rest-java-client-api/2.0.0-m31/jira-rest-java-client-api/apidocs/ (Java Rest API)
  2. https://docs.atlassian.com/jira/7.1.9/index.html?overview-summary.html (JIRA Java API)
  3. https://docs.atlassian.com/jira-servicedesk/3.3.0-REL-0036/ (Java Service Desk API)

I am using 1), but found out that many methods are not available, for example:
Issue.getCustomFieldValue(), and Issue.setCustomFieldValue()
but they are available in 2 - (JIRA Java API)

It seems that Java Rest API is for READ-ONLY: I didn’t see methods for updating, is that correct?
Why there are so many different Java APIs? For what purpose? I am really confused.

For my purpose, which Java API is best to use? Any tutorials to get started with JIRA Java API?
I only saw the tutorials for Java REST API, that’s why I started with it.

Thanks a lot for the help!

The API in 1 is not an API for Jira, it’s for the Jira REST client, which is an application that runs outside Jira and talks to it over REST, reproducing some of the data structures in Jira so you’re not working with plain raw REST formatted data.

The API in 2 is for plain Jira, and in 3, there’s a second API for Jira systems that have Service Desk installed. Point 4 would be that there is another API for Jira with Software as well. These are not exclusive - if you have both applications installed on top of a Core Jira, then all three APIs are available to you.

Finally, there is a plain REST API (this is the one the Jira Rest Java Client talks to). You can talk to that direct if you want, you don’t need the client, and it IS read/write, you can do updates with it.

Which ones you use is up to you and what you’re doing. If your system is going to run inside Jira (as an add-on or application), then you will want to be writing for the Jira internal APIs (i.e. 2, plus 3 and/or 4 if you’re working with those applications). If your system is external to Jira, then forget the internal APIs, you need to use REST. You can use it raw, or you could go via JRJC. I usually find it better to use plain REST, it’s more clear, and most external stuff I do does not need the objects JRJC presents.