Hypermedia

Representational State Transfer (REST) is the software architectural style used by FamilySearch. FamilySearch uses hypermedia as the engine of application state (HATEOAS) and as the basis for programmatic interaction with the server. At FamilySearch, application state is provided by the API resources. Each resource provides information about certain functions that can be performed. Transitioning from one resource to another is accomplished using hypermedia links.

Resources

Examples of FamilySearch resources include:

  • Collection (e.g., FamilySearch Family Tree)
  • Person
  • Spouses
  • Parents
  • Children
  • SourceDescriptions
  • Ancestry
  • Memories
  • Records

FamilySearch Family Tree Resources

To consume the FamilySearch API, links are used at runtime to discover all resources. Hard-coding endpoint URIs is unnecessary, as is constructing URIs to access resources.

The only thing your client needs to access resources is the URI to a collection, such as FamilySearch Family Tree.

Think of the collection resource as the "index page" for the FamilySearch API. By retrieving the collection resource, your client will be able to follow links to all other resources available on the platform. For an explanation of how changes regarding resources are handled, see the API Evolution guide.

An unauthenticated request to the collection resource will return the links for authentication. After authenticating, the collection resource will return links for viewing the current person, searching for a person, creating a person, creating relationships, and other links for getting started.

Read more about REST and Hypermedia.

Person Resource

As an example, the state of a Person is obtained by performing a GET on the Person endpoint. The response contains URIs to endpoints that can be used to transition to other resources. The identifier of a resource is in the link rel. To transition to another resource, simply follow the link rel provided in the current resource response. The following links are examples of some of the links found in the person response.

<link rel="ancestry" 
   href="https://familysearch.org/platform/tree/ancestry?person=PPPJ-MYZ"/>
<link rel="artifacts" 
   href="https://familysearch.org/platform/tree/persons/PPPJ-MYZ/memories"/>
<link rel="change-history" 
   href="https://familysearch.org/platform/tree/persons/PPPJ-MYZ/changes"/>
<link rel="child-relationships" 
   href="https://familysearch.org/platform/tree/persons/PPPJ-MYZ/child-relationships"/>
<link rel="children" 
   href="https://familysearch.org/platform/tree/persons/PPPJ-MYZ/children"/>

Responses

The response is returned in either XML or JSON format, according to the preference you specified in the Accept Header.

To parse and extract the information you want, you must deserialize the response. You can parse the response yourself or use an SDK to deserialize the information you need using the provided functions.

PHP SDK Examples

Serialization and Deserialization

The following code performs serialization and deserialization using the PHP SDK:

// Serialize JSON
$json = $gedcomx->toJson();
// Serialize XML
$xml  = $gedcomx->toXML();

// Deserialize from JSON
$gedcomx = new Gedcomx(json_decode($json, true));
// Deserialize from XML
$xmlReader = new \XMLReader();
$reader->xml($xml);
$gedcomx = new Gedcomx($reader);

Transitioning Resources

The following is an example of transitioning from one resource to another using the PHP SDK. In the following example, the FamilySearch Family Tree Collection is read and transitions to the Person resource:

// Initialize
use Gedcomx\Rs\Client\StateFactory;
use Gedcomx\Rs\Client\PersonState;
use Gedcomx\Conclusion\Person;
$stateFactory = new StateFactory();
$collectionURI = "https://sandbox.familysearch.org/platform/collections/tree";
$accessToken = "{access-token-obtained-from-oauth2}";
// Establish the treeCollectionState as an entry point to all other tree states, such as person
$treeCollectionState = $stateFactory
    ->newCollectionState($collectionURI) //read the collection
    ->authenticateWithAccessToken($accessToken); //set the Access Token
// Transition to the Person State for the current user. The PHP SDK readPersonForCurrentUser 
// method follows the "current-user-person" link to establish the Person state.
$currentPersonState = $treeCollectionState
    ->readPersonForCurrentUser();
// getPerson() is a PHP SDK method that reads the Person object from the Person state data
 $person = $currentPersonState->getPerson();