AtlasCamp2014: Introducing the Confluence REST API

Confluence published the first version of its official, supported REST API in February. The new REST API makes it easy to create, retrieve and manipulate Confluence content with either Atlassian Connect or P2 plugins. Steve Lancashire, a senior developer on the API team, will give you a tour of its capabilities and key features, like new Content Property persistence, expansions to help you get what you need out of the API in a single request, and potential extensions to the API available with P2 plugins.

1. June 3-5, 2014 | Berlin, Germany

2. Steve Lancashire, Senior Developer - Confluence Platform, Atlassian
Introducing the
Confluence REST
API

3. Confluence Platform
Tweet any questions using #confluenceREST

4. Confluence Platform Goal
Make Confluence a simple, fast, reliable
product, and platform supporting
content applications, for the next ten
years.
”
“

5. Confluence Platform

6. Who are our “customers”?
Other
Atlassian!
Devs
Internal!
Confluence!
Devs
Our
Ecosystem!
(you)

7. Remote APIs - the past
SOAP and!
Xml RPC
!
Json
RPC
Prototype
REST!
(read only)
Feature specific
REST Resources

8. Many different APIs
•Developing a feature could end up using all of them!
•RPC and SOAP ignores the architecture of the Web!
•Incompatible representations between APIs!
•No cross version stability for feature specific resources

9. Confluence REST API
Tweet any questions using #confluenceREST

10. •Language agnostic!
•Doesn’t ignore the architecture of the web!
•cross version stability guarantees
Benefits of a REST API

11. Features of our REST API
•Default JSON representation!
•Hypermedia inside entities!
•Embed entities through expansions!
•Common Content model

12. •Paginated, filterable list of content!
•Content is any page, blogpost,
comment or attachment in
Confluence!
•Initially terse, but accepts nested
expansions!
• lets have a look at it
/rest/api/content
GET
Tooltip:!
The most readily available REST client
is your browser install a JSON
formatting extension, like JSONView
for Chrome

13. DEMO - list content
https://confluence.atlassian.com/rest/api/content

14. •Retrieve a piece of content by id!
•has a default set of expansions!
•supports nested, dot separated
expansions!
•example : confluence.atlassian.com/
rest/api/content/12
/api/content/{id}
GET
Tooltip:!
The most readily available REST client
is your browser install a JSON
formatting extension, like JSONView
for Chrome

15. Content Body Representations
STORAGE
EDITOR!
(internal)
VIEW!
(read only)
WIKI!
(write only)

16. •Converts content representations
from one representation to another!
•lets have a look at an example using
cURL!
•you can find more about storage
format on confluence.atlassian.com!
!
!
!
…/contentbody/convert/{to}
POST
Tooltip:!
cURL is a simple command line tool,
there are some cUrl examples using
the new REST API on
developer.atlassian.com

17. DEMO - Convert content
curl -u admin:admin -X POST -H 'Content-Type: application/json'
-d'{"value":"<ac:structured-macro ac:name=\"cheese\" /
>","representation":"storage"}' "http://localhost:8080/confluence/
rest/api/contentbody/convert/view" | python mjson.tool

18. •Creates a new piece of content!
•Similar required fields as creating
content in the Confluence Editor!
•create from STORAGE, EDITOR
or WIKI content representations!
•returns the new piece of content
with generated id
/api/content/
POST
Tooltip:!
The REST API Browser on Atlassian
Marketplace provides a useful UI for
exploring the REST API

19. DEMO - Creating Content
http://localhost:8080/confluence/plugins/servlet/restbrowser#/resource/api-content/POST
!
{
"title" : "Atlascamp 2014",
"type" : "page",
"body" : {
"storage" : {"value" : "<p>Hi everyone</p>", “representation":"storage"}
},
"space" : {"key":"DS"}
}

20. •Modify and delete existing content!
•Modifying requires an explicit version increment!
•DELETE removes the content from the resource
and moves it to the trash
/api/content/{id}
PUT / DELETE

21. DEMO - Updating Content
https://stevelan.jira-dev.com/wiki/plugins/servlet/restbrowser#/resource/api-content-id/PUT
!
{
"id":4685825,
"type":"page",
“body":{"storage":
{
"representation":"storage",
"value":"<p>Hi to everyone else</p>“}
},
"version":{"number":2}
}

22. Content Properties
A key / value store for the REST API

23. Content Properties
•Key / value store of properties on
content!
•Store up to 32KB of JSON!
•Great for Atlassian Connect

24. •Collection of properties on a piece of content!
•GET to fetch all properties !
•POST to create a new property!
!
/api/content/{id}/property
GET / POST
/api/content/{id}/property/arbitrary-key

25. •GET a particular property by specifying the key!
•PUT the value to update!
•DELETE removes the property
/api/content/{id}/property/{key}
GET / PUT / DELETE
{!
!!“key” : “arbitrary-key”, !
!!“value” : { “random-json“: “data” } !
!!...!
}
/api/content/{id}/property/arbitrary-key

26. DEMO - add a property
chrome://apps/

27. •spaces, child content, content
history, labels!
•API Reference docs can be found
via developer.atlassian.com!
•or google : confluence rest api docs
Plus lots more

28. •More small script examples on developer.atlassian.com
More examples

29. •Can extend the API with
metadata!
•P2 plugins can surface their
feature through the API!
•Implement
ModelMetadataProvider interface
Extending the API
ADVANCED TOPICS

30. •Capabilities API since Confluence 5.0!
•provides api “feature” discovery!
•confluence-content-api indicates the presence of the api
Migrating to the new API
ADVANCED TOPICS
“application” : “confluence”, !
“capabilities” : {!
!! “confluence-content-api“ : “/rest/api/content”,!
!! !… !
}
/rest/capabilities

31. So what is next?

32. CQL
Confluence Query Language for the REST API

33. •Query language for finding content !
•Similar to JQL / SQL where clause!
•API only, not user facing!
•i.e.: space in (DEV, DOCS) and title ~ “rest api”!
What is CQL?

34. •Flexible!
•Fast!
•Familiar
CQL Benefits

35. Functions!
•similar to JQL functions!
•i.e. creator = currentUser()
Extensibility
CQL BENEFITS
Fields!
•plugins can add indexed fields to the CQL grammar!
•i.e. macro = cheese

36. !
•https://pug.jira.com/wiki/plugins/cqlsearch/cql.action
Demo

37. Before and After

38. 1.0 - MVP!
•Existing fields in the index!
•Extensible fields and functions!
•Operators : =, !=, ~, !~, <=, >=,
IN, NOT IN, EMPTY
•1.1 Expand the index!
•Indexing service for plugins!
•Additional fields from plugin
data stored in AO!
•Content properties
CQL Roadmap

39. Questions
Tweet any questions using #confluenceREST

40. Thank you
Go build something awesome!