Saving Documents With an SDK

Irakli Nadareishvili edited this page Jan 17, 2014 · 21 revisions

Saving Documents over HTTP

To save a document to PMP API you need to:

  1. Make a request to the Home Document (e.g., note the edit link. At the time of writing this property points to an array which contains save-related links, one of which allows saving a document (please note the corresponding relationship in rels):

    "edit" : [
        "title": "Document Save"
      , "rels": [ "urn:collectiondoc:form:documentsave" ]
      , "href-template": "{/guid}"
      , "href-vars": { "guid": "" }
      , "hints": {
          "allow": ["PUT", "DELETE"]
        , "docs": ""
        , "formats": ["application/vnd.pmp.collection.doc+json"]
    , {...}

    which means: "to edit a document, make an HTTP PUT request to endpoint"

  2. You need to make an HTTP request to the endpoint resolved with step #1, using the HTTP method resolved in step #1. The HTTP body of the request should be JSON document of Collection.doc+JSON media type that you are trying to save. The document submitted must include required properties as indicated in the media type specification: At the time of writing of this document, the only required fields is: guid.

  3. PMP API intentionally doesn't save documents without a pre-defined GUID. A client is responsible for generating proper, UUDv4-compliant GUID for a document. If you don't want to create a proper GUID on the client-side or it's hard to do so, API provides an endpoint to generate one for you.

  4. The URL of the GUID-generator endpoint is provided by the "guid" link of the Home Document response. At the time of writing of this document, for Sandbox environment, it looks something like the following:

          "href": "",
          "title": "Generate guids",
          "rels": [
          "method": "POST",
          "type": "application/json"

Using SDK:


require_once(dirname(__FILE__) . '/phpsdk/lib/Pmp/Sdk/AuthClient.php');
require_once(dirname(__FILE__) . '/phpsdk/lib/Pmp/Sdk/CollectionDocJson.php');
require_once(dirname(__FILE__) . '/phpsdk/lib/Pmp/Sdk/Exception.php');

use \Pmp\Sdk\AuthClient as AuthClient;
use \Pmp\Sdk\CollectionDocJson as CollectionDocJson;
use \Pmp\Sdk\Exception as Exception;

$host = '';
$client_id = "...redacted...";
$client_secret = "...redacted...";

try {
  $auth = new AuthClient($host, $client_id, $client_secret);
} catch (Exception $ex) {
  die(print_r($ex->getMessage(), true));

if ($auth->getToken()->token_expires_in < 10) {
    die("Access token expires too soon. Not enough time to make a request. Mayday, mayday");

$doc = createSampleDocument($host);
saveDoc($host, $auth, $doc);


function saveDoc($host, $auth, $document) {
    try {
        $docClient = new CollectionDocJson($host, $auth);
        echo "Saved " . $docClient->getUri() . " " . $docClient->attributes->title . "\n";
    } catch (Exception $e) {
        echo "Failed " . $host . " " . $document->attributes->guid . " " . $document->attributes->title . "\n";

function createSampleDocument($host) {
    $doc = new \stdClass;
    $doc->version = '1.0';
    $doc->attributes->guid = 'f337b489-1e9a-4860-8a58-d12e7fe78784';
    $doc->attributes->tags = array('testcontent');
    $doc->attributes->title = 'Sample content title';

    $profileLink = new \stdClass;
    $profileLink->href = $host . '/profiles/story';
    $doc->links->profile[0] = $profileLink;

    return $doc;

If you don't indicate $doc->attributes->guid, SDK will generate a unique UUID v4 identifier and save the document with a new identifier.

Deleting a Document:

Note: Before executing the code below you need to initialize a docClient as you would normally (@see up).


// Create a placeholder doc with a real GUID, or use one loaded from the server:
$doc = new \stdClass;
$doc->version = '1.0';
$doc->attributes->guid = 'f337b489-1e9a-4860-8a58-d12e7fe78784';

$docClient = new CollectionDocJson($host, $auth);