Upload
atlassian
View
1.707
Download
0
Tags:
Embed Size (px)
DESCRIPTION
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.
Citation preview
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
• 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!