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. https://api-sandbox.pmp.io/), 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": "https://publish-sandbox.pmp.io/docs{/guid}"
      , "href-vars": { "guid": "http://docs.pmp.io/wiki/Globaly-Unique-Identifiers-for-PMP-Documents" }
      , "hints": {
          "allow": ["PUT", "DELETE"]
        , "docs": "http://docs.pmp.io/wiki/Collection.doc-JSON-Media-Type"
        , "formats": ["application/vnd.pmp.collection.doc+json"]
        }
      }
    , {...}
    ]

    which means: "to edit a document, make an HTTP PUT request to https://publish-sandbox.pmp.io/docs 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: https://github.com/publicmediaplatform/pmpdocs/wiki/Collection.doc-JSON-Media-Type. 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": "https://api-sandbox.pmp.io/guids",
          "title": "Generate guids",
          "rels": [
              "urn:pmp:query:guids"
          ],
          "method": "POST",
          "type": "application/json"
      },

Using SDK:

<?php

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 = 'https://api-sandbox.pmp.io';
$client_id = "...redacted...";
$client_secret = "...redacted...";

try {
  $auth = new AuthClient($host, $client_id, $client_secret);
  print_r($auth->getToken());
} 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);

die("Success");


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

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

<?php

// 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);
$docClient->setDocument($doc);
$docClient->delete();