The document summarizes the Confluence REST API introduced by Steve Lancashire of Atlassian. The REST API provides a language-agnostic way to access and modify Confluence content and properties using RESTful endpoints. Key points include: 1. The REST API allows accessing Confluence content and properties through REST resources and representations like JSON for cross-platform development. 2. Demonstrations show listing content, converting representations, creating and updating content, and adding properties through REST calls. 3. The Confluence Query Language (CQL) provides a query syntax for flexibly finding content through the REST API similar to SQL, benefiting performance, flexibility, and extensibility.

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!