Improve API documentation and examples for submitting commands

I am not sure if it is possible to allow non-puppet client to do command "replace facts" into puppetdb. I tried "replace facts" puppetdb API, and kept getting the following errors:

2013-06-28 02:20:25,003 ERROR [command-proc-94] [puppetdb.command] [9e05098c-6088-428e-92bd-fbb68cc63387] [replace facts] Retrying after attempt 11, due to: java.lang.AssertionError: Assert failed: (string? certname)

It is supported, but the documentation doesn’t show good examples on how to do this yourself: http://docs.puppetlabs.com/puppetdb/latest/api/commands.html. Here is a snippet that worked for me:

# curl -X POST -H "Accept: application/json" -d 'payload={"command":"replace facts","version":1,"payload":"{\"name\":\"test1\",\"values\":{\"myfact\":\"myvalue\"}}"}' http://localhost:8080/v2/commands

{

  "uuid" : "960c0e13-0d5a-4a5a-b2ef-970ce61816a1"

}

# curl -H "Accept: application/json" 'http://localhost:8080/v2/facts?query='

[ {

  "certname" : "test1",

  "name" : "myfact",

  "value" : "myvalue"

} ]

Of special note, is the ‘payload’ contents in JSON are escaped, this is because its a JSON string inside another JSON string, so you have to serialize the payload part.