Is there a working API for posting comments in Confluence?

[Justin Alan Ryan]

The REST example, at:

  https://developer.atlassian.com/confdev/confluence-rest-api/confluence-rest-api-examples#ConfluenceRESTAPIExamples-Addacommenttoapage%28python%29

Well, where do I start?  First, to even read it, let alone attempt to run it, one must convert and remove HTML entities.

Now that you can read and run this script, you'll want to replace localhost:80 with the URL of a hosted Atlassian instance, and, at least in our case, also replace /confluence/ with /wiki/, substituting known creds in your instance for admin/admin in the example.

Now, fancy things start to happen! The first part of the script, which performs a search to get the id and other info about the page, works correctly.  If I print the JSON, it describes the page I'm trying to post to.

The second part, which conjures JSON to post the comment itself, results in a response which, if I run the script with python -i and print request.text, is literally a random ass page in the wiki, seemingly created as a test by our CTO months ago.  It might be the first page in the wiki, I can't really confirm that.

--

I'm sure, if you've read this far, you're all, "Dude!  There's documentation for the REST API!  Just read!"

Is there?  Really?  Documentation for the REST API?  Let's take a look!

Ohai, on https://developer.atlassian.com/confdev/confluence-rest-api , there's a link to the above page!

Let's skip that, since we've been there.  Here's the documentation for the REST API that the Python example above is POST-ing to:

  https://docs.atlassian.com/atlassian-confluence/REST/latest/#d3e865

So, the documentation for GET specifies the possible valid values for "type" as "page" and "blogentry".  I'm willing to accept that POST may have a special case for "type":"comment", but the documentation for POST literally just confirms that you can POST.

--

Now, you might be like, "Again, dude, there's an API browser!  Why not try that?"  Well, first, I'm going to say it should be safe to assume that the API browser would not contain more information than the documentation, but I'll tell you how hard I tried to solve this ridiculously stupid problem - I tried to use the API Browser.

The documentation provides unix commands for running on my Confluence server to run, tells me to install an Plugin SDK, etc..  I don't have a Confluence server, I don't want to write plugins, I just want to use this one API in hosted Confluence. 

--

So, Confluence community - please assist!  I'd love to even contribute a fix for the documentation to Atlassian.

I just.. just... really want to post a comment from Hubot, but I can translate the Python to Coffee Script.  As a matter of fact, I already have.  I didn't even try the python example until I wanted a more familiar language to figure out why my CoffeeScript wasn't working.

I'm pretty sure it's not my CoffeeScript, having spent many hours with this python code.

[Stephen Deutsch]

Hi Justin,

The REST API works just fine for posting comments.  It's true that the documentation is bad, but the implementation is actually fairly well put together.  You just define a parent (container) by including the return from the content call and simply put in the necessary fields.  Here's an example using jQuery (you can test it by copy and pasting into the Javascript console) which could be adjusted as necessary:

var pageId = 98334;
jQuery.ajax({
  url: contextPath + "/rest/api/content/" + pageId,
  success: function(parentPage) {
    var pageData = {}
    pageData.type = 'comment';
    pageData.container = parentPage;
    pageData.body = {};
    pageData.body.storage = {};
    pageData.body.storage.value = "<p>A new comment</p>"
    pageData.body.storage.representation = 'storage';
    jQuery.ajax({
      contentType: 'application/json',
      type: 'POST',
      url: contextPath + "/rest/api/content",
      data: JSON.stringify(pageData),
    });
  }
});

Hope that helps!

[Justin Alan Ryan]

Stephen - Thanks, I appreciate the response! It's not clear to me at a glance how this example is better, or really any different, than the example which doesn't work, though I appreciate it isn't full of HTML entities I don't have to scrub. ;) Additionally, I don't understand how this would work in JS console. Is this assuming I run it in my browser while i'm already logged in?

[Bernie Maier]

talking about INLINE Comments ...

how would you do?

you have to post the location of the content to comment and the comment-content...
...but how to reference the location?
...and what if it is already commented?
...and how to avoid bad nesting of ac:inline-comment-markers?
...and what about answers to comment?

sure, the frontend is doing all this - but how would you do from within the rest api?

[Chii]

the existing xml-rpc has a method for posting comments. you can find the documentation on it here. There is a corresponding json-rpc, which allows you to perform them via javascript in the browser with more ease. These apis are due to be deprecated, and will eventually be replaced by the rest api, but while it is being fleshed out, you should be able to continue to use xml-rpc for all your api needs.

[Justin Alan Ryan]

So the new REST API is not available yet? I think that could be more clearly expressed in the documentation, and that providing a timeline would be best. The best I can think of is to set a 15 minute meeting once a month to check whether the new API has been released / the RPC APIs have been killed yet. ;) This code will be 'production' for us as part of our DevOps process / environment. The Confluence API is literally the wall between Dev and Ops right now. ;)

[Davin Studer]

Right now the REST API is pretty limited in what it can do. I would imagine since the inline commenting is a new feature that the REST API doesn't support it yet. And I wholeheartedly agree that the REST documentation stinks. They should take a note from the jQuery team on how to do API documentation.

[Justin Alan Ryan]

Thanks for the answer Davin! To clarify, since I know my epic poem above is a bit easy to TL;DR, it seems like at some point, an Atlassian employee wrote and tested a python script for making comments. This python script is in a REST API that self-identifies as out of date, though usable for "prototyping", and replaced by a new REST API. The question I considered posting was, "Where in the world is the documentation for the new REST API?!", but I thought this would be more fun, and that I might get an exact answer. I can always move onto that. Does the new REST API do _less_? Please don't make me cry today.. ;)

[Justin Alan Ryan]

er, "is in a REST API" .. should be "uses a REST API"

[Nic Brough -Adaptavist-]

I tldr'd the bit on "coffee" in your essay (because I've not decided coffee is the best way to do anything I need to do yet, and I sort of like drinking the nice Klatchian stuff rather than coding in it), but the rest of it was a huge pile of "yup". As Davin says, the documentation feels wrong to me. I can follow a lot of Atlassian docs and they work for me. I put a lot of that down to me having worked with their stuff for <mumble> years and having a good feel for what they're writing about. But using Confluence over REST... not a clue. I've been lucky and avoided needing to do it, but sadly might have to soon (I will be putting the headache pills on an expense claim) The main reason I'm commenting though is a snippet of good news - the new REST API provides all the functions of the prototype, and a bit more. (Although I suspect some of the interface has changed how you talk to it, different parameters etc, you should be able to do everything you could do with the old one)

[Davin Studer]

I totally read you question wrong. I thought you were asking about the new inline comments in 5.7. Yes, the regular comments are supported. Sorry.

[Stephen Deutsch]

That's true; it seems like you can read inline comments, but there doesn't seem to be a way to set one yourself yet (since it uses a field called markerRef which is not clear how it is generated; perhaps it can so far only be done on the backend).