The existence of an API allows developers to extend software so as to cater for unique use cases beyond the software's original scope. Administrators and end users of JIRA 5 can expect its REST API to enable the creation of integrated applications to solve their unique concerns. This presentation aims to describe ways in which the JIRA 5 REST API can be used to make a tangible impact for the end user. Several use cases will be discussed, ranging from running simple command line apps, through to creating web applications that integrate with the JIRA 5 REST API.

2. Extend your use of JIRA.
Solve your unique concerns.
An exposé of the new JIRA 5 REST API
Abhinav Keswani // @wasabhi
Principal, Bespoke Solutions // trineo.com.au // @trineoltd

3. What lies ahead?
• JIRA 5 REST API
• Structure, Authentication, and Entity Expansion
• Remote Apps: Key concepts.
• How to begin? Useful resources.
• In the wild: Use cases and examples of web apps.

4. REST
(an extremely brief overview)

5. Representational State Transfer

6. Representational State Transfer
• Client/Server requests/responses are to facilitate the
transfer of representations of resources.

7. Representational State Transfer
• Client/Server requests/responses are to facilitate the
transfer of representations of resources.
• Resources are sources of specific information with a
unique identifier.

8. Representational State Transfer
• Client/Server requests/responses are to facilitate the
transfer of representations of resources.
• Resources are sources of specific information with a
unique identifier.
• Uniform interface; identify/manipulate resources, self
descriptive messages, hypermedia used for application
state.

9. Hearing @wasabhi talk about the JIRA 5 REST API -
a uniform interface for extensive integration.
#summit12

10. JIRA 5 REST API

11. Resources

13. ASSIGNEE
COMMENT
VOTES ISSUE
WATCHERS
WORKLOG

14. ASSIGNEE
COMMENT
VOTES ISSUE
WATCHERS
WORKLOG
COMPONENTS
PROJECT VERSIONS

15. ASSIGNEE
COMMENT
VOTES ISSUE
WATCHERS
USER WORKLOG
COMPONENTS
PROJECT VERSIONS

16. ASSIGNEE
SEARCH COMMENT
VOTES ISSUE
WATCHERS
USER WORKLOG
COMPONENTS
PROJECT VERSIONS

17. ASSIGNEE
SEARCH COMMENT
VOTES ISSUE FILTER
WATCHERS
USER WORKLOG
COMPONENTS
PROJECT VERSIONS

18. FIELD
ASSIGNEE
SEARCH COMMENT
VOTES ISSUE FILTER
WATCHERS
USER WORKLOG
COMPONENTS
PROJECT VERSIONS

19. REST URI Structure

20. REST URI Structure
http://host:port/context/rest/api-name/api-version/resource-name

21. REST URI Structure
http://host:port/context/rest/api-name/api-version/resource-name
http://example.com:8080/jira/rest/api/2/issue [POST]

22. REST URI Structure
http://host:port/context/rest/api-name/api-version/resource-name
http://example.com:8080/jira/rest/api/2/issue [POST]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey} [GET, DELETE, PUT]

23. REST URI Structure
http://host:port/context/rest/api-name/api-version/resource-name
http://example.com:8080/jira/rest/api/2/issue [POST]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey} [GET, DELETE, PUT]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey}/assignee [PUT]

24. REST URI Structure
http://host:port/context/rest/api-name/api-version/resource-name
http://example.com:8080/jira/rest/api/2/issue [POST]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey} [GET, DELETE, PUT]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey}/assignee [PUT]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey}/comments [GET, POST]

25. REST URI Structure
http://host:port/context/rest/api-name/api-version/resource-name
http://example.com:8080/jira/rest/api/2/issue [POST]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey} [GET, DELETE, PUT]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey}/assignee [PUT]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey}/comments [GET, POST]
http://example.com:8080/jira/rest/api/2/issue/{issueIdOrKey}/comment/{id} [GET, PUT, DELETE]

26. Authentication
HTTP BASIC (SSL)
OAUTH
...and...
HTTP Cookies, Trusted Applications, OS Username & Password

27. Response Notation
JSON

28. OAuth (1.0a)

29. Your app is the “Consumer”.
JIRA is the “Service Provider”.
You must register your app as an
“application link”, which can be identified
by JIRA using a “consumer key”, and a
public key (x509 RSA-SHA1).

30. • You request a token from the service provider.
• Do this by presenting a signed request including
your consumer key.
Consumer. Service Provider
Request Grant
Request Token Request Token

31. • The service provider grants you a request token.
• The token does not authorize you yet.
• The end user must authenticate with the service
provider and authorize access for the consumer.
Consumer. Service Provider
Direct End User to Obtain
Service Provider User Authorization
Direct End User
To Consumer

32. • The end user authorized Consumer access, and the
Consumer was presented with an oauth token.
• Use the oauth token to request an access token
from the Service Provider.
Consumer. Service Provider
Request Grant
Access Token Access Token
Access
Protected Resources

33. Entity Expansion

34. Entity Expansion
The expand query parameter allows a comma-separated
list of identifiers to expand.
The motivation is to save CPU and network traffic.

35. Entity Expansion
Specify expansion of entities within another entity using
dot notation. For example
?expand=starships.warp
expands the starships collection and also the warp
property on each starship.

36. remoteapps

37. Remoteapps Key Concepts
A Remote App is a web application that
runs outside the Atlassian application, and
yet is accessible by it.

38. Remoteapps Key Concepts
As a result, no code is executed on the
Atlassian application, but instead, content
from the Remote App is included in
Atlassian application pages or rendering
processes.

39. Remoteapps Key Concepts
In the other direction, a Remote App can
subscribe to key events via web hooks to
enable more complex workflow
integrations.

40. Remoteapps Key Concepts
Communication to and from the Remote
App is secured through OAuth.

41. Remoteapps Key Concepts
Remote Apps can be written in any
application language and deployed on any
server, as long as it is reachable from the
Atlassian application over web protocols.

42. Key Concepts
★ Secure
★ You are in control of
★ form and function
★ performance and scale
★ Bi directional communication yields
superb efficient result

43. Go learn more ...
Don Brown: Plugins OnDemand
with RemoteApps.
...tomorrow 11:20-12:00

44. Useful Resources

45. Choose your weapon.
• Customise your integration. CLI or Web usage.
• JIRA Java REST Client (JRJC)
• JIRA Ruby Gem
• Python CLI for JIRA
• JIRA Issue Collector (JavaScript)

46. Go learn more ...
Ben Speakmon: JIRA REST Client
for Python.
...tomorrow 14:50-15:00

47. Oodles of great docs...

48. Quick look at the Ruby gem.

49. In The Wild

50. JIRA on Ruby Console

51. JIRA on Rails

52. Thanks @wizzfiz for letting @wasabhi come out to
play!
#summit12

53. Documentation
https://developer.atlassian.com/static/rest/jira/5.0.html
https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API
+Tutorials
https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API
+Example+-+OAuth+authentication
https://developer.atlassian.com/display/REST/REST+API
+Developer+Documentation
http://www.25hoursaday.com/weblog/2008/08/17/
ExplainingRESTToDamienKatz.aspx

54. Thank you!