AtlasCamp2014: Introducing the Confluence REST API

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, for the next ten years. ”

“

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 Web!• Incompatible representations between APIs!• No cross version stability for feature specific resources

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 API

Features of our REST API

• Default JSON representation!• Hypermedia inside entities!• Embed entities through expansions!• Common Content model

• 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/contentGET

Tooltip: The most readily available REST client

is your browser install a JSON formatting extension, like JSONView

for Chrome

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!• 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

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 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

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

• 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

DEMO - Creating Contenthttp://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"} }

• 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

DEMO - Updating Contenthttps://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} }

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/content/{id}/propertyGET / POST

/api/content/{id}/property/arbitrary-key

• 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

DEMO - add a property

chrome://apps/

• 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

• 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 ModelMetadataProvider interface

Extending the APIADVANCED TOPICS

• Capabilities API since Confluence 5.0!• provides api “feature” discovery!• confluence-content-api indicates the presence of the api

Migrating to the new APIADVANCED TOPICS

“application” : “confluence”, !“capabilities” : {! !! “confluence-content-api“: “/rest/api/content”,!!! ! … !}

/rest/capabilities

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 (DEV, DOCS) and title ~ “rest api”!

What is CQL?

• Flexible!• Fast!• Familiar

CQL Benefits

Functions!• similar to JQL functions!• i.e. creator = currentUser()

ExtensibilityCQL BENEFITS

Fields!• plugins can add indexed fields to the CQL grammar!• i.e. macro = cheese

!

• 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, EMPTY

• 1.1 Expand the index!• Indexing service for plugins!

• Additional fields from plugin data stored in AO!

• Content properties

CQL Roadmap

Questions Tweet any questions using #confluenceREST

Thank you Go build something awesome!