Querying Documents With an SDK

David Moore edited this page Jan 23, 2014 · 20 revisions

Getting Started

The responses of the PMP API are of the media type: Collection.doc+JSON. Collection.doc+JSON is basically a JSON document that has the following structure:

Collection.doc+JSON Diagram

  1. It has attributes: a set of properties describing content of the document
  2. It has links: hyperlinks pointing to queries you can perform on the related documents, pagination links for large documents, action links that communicate how to save the document etc.
  3. It has 'errors' object that can provide additional information about possible errors.

Querying the Home Document

Home Document of the API is the document that is returned when you visit the root URL of the API: https://api-sandbox.pmp.io. Since it doesn't contain much of useful data, it's most useful part is the links array of the query link relation, messaging to the API client various queries that can be run against the API.

Let's use the SDK to retrieve this document and inspect various query types:

<?php

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

$host = 'https://api-sandbox.pmp.io';
$client_id = "...redacted...";
$client_secret = "...redacted...";

$auth = new \Pmp\Sdk\AuthClient($host, $client_id, $client_secret);

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

$doc = new \Pmp\Sdk\CollectionDocJson($host, $auth);

$query_link_types = $doc->links('query')->queryRelTypes();
print_r($query_link_types);
exit(0);

should return:

Array
(
    [urn:collectiondoc:query:users] => Query for users
    [urn:collectiondoc:query:groups] => Query for groups
    [urn:collectiondoc:hreftpl:profiles] => Access profiles
    [urn:collectiondoc:query:profiles] => Query for profiles
    [urn:collectiondoc:hreftpl:schemas] => Access schemas
    [urn:collectiondoc:query:schemas] => Query for schemas
    [urn:collectiondoc:hreftpl:docs] => Access documents
    [urn:collectiondoc:query:docs] => Query for documents
    [urn:collectiondoc:query:guids] => Generate guids
)

Query Relationship Type URNs

What are the funky contents of the array in the example above, you ask? They are the unique identifier URNs that allow an API client to uniquely distinguish and identify various Query Link Types in an API response.

Using a Query Link, an API client can either follow a query link or submit a template-ed query to the API.

Available Options for a Query Type

To see a full list of various options that a specific query can be customized by, and the links to documentation for each option:

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

$host = 'https://api-sandbox.pmp.io';
$client_id = "...redacted...";
$client_secret = "...redacted...";

$auth = new \Pmp\Sdk\AuthClient($host, $client_id, $client_secret);
$doc = new \Pmp\Sdk\CollectionDocJson($host, $auth);

$URN = 'urn:collectiondoc:query:docs';
print_r($doc->query($URN)->options());

which should return (at the time of writing this wiki):

stdClass Object
(
    [guid] => http://docs.pmp.io/wiki/Content-Retrieval
    [limit] => http://docs.pmp.io/wiki/Content-Retrieval
    [offset] => http://docs.pmp.io/wiki/Content-Retrieval
    [tag] => http://docs.pmp.io/wiki/Content-Retrieval
    [collection] => http://docs.pmp.io/wiki/Content-Retrieval
    [text] => http://docs.pmp.io/wiki/Content-Retrieval
    [searchsort] => http://docs.pmp.io/wiki/Content-Retrieval
    [has] => http://docs.pmp.io/wiki/Content-Retrieval
    [author] => http://docs.pmp.io/wiki/Content-Retrieval
    [distributor] => http://docs.pmp.io/wiki/Content-Retrieval
    [distributorgroup] => http://docs.pmp.io/wiki/Content-Retrieval
    [startdate] => http://docs.pmp.io/wiki/Content-Retrieval
    [enddate] => http://docs.pmp.io/wiki/Content-Retrieval
    [profile] => http://docs.pmp.io/wiki/Content-Retrieval
    [language] => http://docs.pmp.io/wiki/Content-Retrieval
)

A Search for Sample Content

PMP API comes pre-loaded with some sample content to make exploration of the API more intuitive. The sample content is tagged with the 'samplecontent' free-form tag. Let's see how we can retrieve all content tagged with such tag:


<?php

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

$host = 'https://api-sandbox.pmp.io';
$client_id = "...redacted...";
$client_secret = "...redacted...";

try {
  $auth = new \Pmp\Sdk\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");
}

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

try {
    $doc = new \Pmp\Sdk\CollectionDocJson($host, $auth);
} catch (Exception $ex) {
    die(print_r($ex->getMessage(), true));
}

$URN = 'urn:collectiondoc:query:docs';
$options = array( "tag" => "samplecontent", "profile" => "story" );

try {
    $search_results = $doc->query($URN)->submit($options);
    // or, the same more verbosely:
    // $doc_search_links = $doc->links('query')->rels(array($URN));
    // $search_results = $doc_search_links[0]->submit($options);
} catch (Exception $ex) {
    die(print_r($ex, true));
}

$result_items = $search_results->items()->toArray();

if (is_array($result_items)) {
  foreach ($result_items as $item) {
      $obj = new stdClass;
      $obj->title = $item->attributes->title;
      $obj->url   = $item->links->navigation[0]->href;
      $obj->profile = $item->links->profile[0]->href;
      print_r($obj);

  }
} else {
  die ("No results");
}

die ("Done");

To see full list of search queries supported in the current version of PMP API: https://github.com/publicmediaplatform/pmpdocs/wiki/Content-Retrieval