June 3-5, 2014 | Berlin, Germany
Steve Lancashire, Senior Developer - Confluence Platform, Atlassian
Introducing the
Confluence REST
API
Confluence Platform
Tweet any questions using #confluenceREST
Confluence Platform Goal
Make Confluence a simple, fast, reliable
product, and platform supporting
content applications, fo...
Confluence Platform
Who are our “customers”?
Other
Atlassian	

Devs
Internal	

Confluence	

Devs
Our
Ecosystem	

(you)
Remote APIs - the past
SOAP and	

Xml RPC
!
Json
RPC
Prototype
REST	

(read only)
Feature specific
REST Resources
Many different APIs
• Developing a feature could end up using all of them!
• RPC and SOAP ignores the architecture of the ...
Confluence REST API
Tweet any questions using #confluenceREST
• Language agnostic!
• Doesn’t ignore the architecture of the web!
• cross version stability guarantees
Benefits of a REST...
Features of our REST API
• Default JSON representation!
• Hypermedia inside entities!
• Embed entities through expansions!...
• Paginated, filterable list of content!
• Content is any page, blogpost,
comment or attachment in
Confluence!
• Initially t...
DEMO - list content
https://confluence.atlassian.com/rest/api/content
• Retrieve a piece of content by id!
• has a default set of expansions!
• supports nested, dot separated
expansions!
• exa...
Content Body Representations
STORAGE EDITOR	

(internal)
VIEW	

(read only)
WIKI	

(write only)
• Converts content representations
from one representation to another!
• lets have a look at an example using
cURL!
• you ...
DEMO - Convert content
curl -u admin:admin -X POST -H 'Content-Type: application/json'
-d'{"value":"<ac:structured-macro a...
• Creates a new piece of content!
• Similar required fields as creating
content in the Confluence Editor!
• create from STOR...
DEMO - Creating Content
http://localhost:8080/confluence/plugins/servlet/restbrowser#/resource/api-content/POST
!
{
"title"...
• Modify and delete existing content!
• Modifying requires an explicit version increment!
• DELETE removes the content fro...
DEMO - Updating Content
https://stevelan.jira-dev.com/wiki/plugins/servlet/restbrowser#/resource/api-content-id/PUT
!
{
"i...
Content Properties
A key / value store for the REST API
Content Properties
• Key / value store of properties on
content!
• Store up to 32KB of JSON!
• Great for Atlassian Connect
• Collection of properties on a piece of content!
• GET to fetch all properties !
• POST to create a new property!
!
/api/...
• GET a particular property by specifying the key!
• PUT the value to update!
• DELETE removes the property
/api/content/{...
DEMO - add a property
chrome://apps/
• spaces, child content, content
history, labels!
• API Reference docs can be found
via developer.atlassian.com!
• or goog...
• More small script examples on developer.atlassian.com
More examples
• Can extend the API with
metadata!
• P2 plugins can surface their
feature through the API!
• Implement
ModelMetadataProvi...
• Capabilities API since Confluence 5.0!
• provides api “feature” discovery!
• confluence-content-api indicates the presence...
So what is next?
CQL
Confluence Query Language for the REST API
• Query language for finding content !
• Similar to JQL / SQL where clause!
• API only, not user facing!
• i.e.: space in (...
• Flexible!
• Fast!
• Familiar
CQL Benefits
Functions!
• similar to JQL functions!
• i.e. creator = currentUser()
Extensibility
CQL BENEFITS
Fields!
• plugins can add...
!
• https://pug.jira.com/wiki/plugins/cqlsearch/cql.action
Demo
Before and After
1.0 - MVP!
• Existing fields in the index!
• Extensible fields and functions!
• Operators : =, !=, ~, !~, <=, >=,
IN, NOT IN...
Questions
Tweet any questions using #confluenceREST
Thank you
Go build something awesome!
Upcoming SlideShare
Loading in...5
×

AtlasCamp2014: Introducing the Confluence REST API

2,590
-1

Published on

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.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,590
On Slideshare
0
From Embeds
0
Number of Embeds
8
Actions
Shares
0
Downloads
13
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

AtlasCamp2014: Introducing the Confluence REST API

  1. 1. June 3-5, 2014 | Berlin, Germany
  2. 2. Steve Lancashire, Senior Developer - Confluence Platform, Atlassian Introducing the Confluence REST API
  3. 3. Confluence Platform Tweet any questions using #confluenceREST
  4. 4. Confluence Platform Goal Make Confluence a simple, fast, reliable product, and platform supporting content applications, for the next ten years. ” “
  5. 5. Confluence Platform
  6. 6. Who are our “customers”? Other Atlassian Devs Internal Confluence Devs Our Ecosystem (you)
  7. 7. Remote APIs - the past SOAP and Xml RPC ! Json RPC Prototype REST (read only) Feature specific REST Resources
  8. 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. 9. Confluence REST API Tweet any questions using #confluenceREST
  10. 10. • Language agnostic! • Doesn’t ignore the architecture of the web! • cross version stability guarantees Benefits of a REST API
  11. 11. Features of our REST API • Default JSON representation! • Hypermedia inside entities! • Embed entities through expansions! • Common Content model
  12. 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. 13. DEMO - list content https://confluence.atlassian.com/rest/api/content
  14. 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. 15. Content Body Representations STORAGE EDITOR (internal) VIEW (read only) WIKI (write only)
  16. 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. 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. 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. 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. 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. 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. 22. Content Properties A key / value store for the REST API
  23. 23. Content Properties • Key / value store of properties on content! • Store up to 32KB of JSON! • Great for Atlassian Connect
  24. 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. 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. 26. DEMO - add a property chrome://apps/
  27. 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. 28. • More small script examples on developer.atlassian.com More examples
  29. 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. 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. 31. So what is next?
  32. 32. CQL Confluence Query Language for the REST API
  33. 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. 34. • Flexible! • Fast! • Familiar CQL Benefits
  35. 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. 36. ! • https://pug.jira.com/wiki/plugins/cqlsearch/cql.action Demo
  37. 37. Before and After
  38. 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. 39. Questions Tweet any questions using #confluenceREST
  40. 40. Thank you Go build something awesome!
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×