Working draft for Genealogies Sync

genealogies-api-details.md

Syncing Data to Genealogies

In order to sync data to the Genealogies system, use the following process:

1. Obtain access token for the user.
2. Create a new Genealogies Tree.
3. Add data to the Genealogies Tree.
4. Update persons and relationships.
5. Get the matches.

Step 1: Obtain access token for the user

This is accomplished by sending the user through the OAuth 2 authentication and authorization process. More information can be found here.

Step 2: Create a Genealogies Tree

A Tree in the Genealogies system is the container which will hold all of the tree persons and information regarding the user's tree. This is roughly equivalent to the user's file containing tree information for a desktop genealogy application. A user can create and access multiple trees, so it is important to keep a mapping to the ID of the tree created.

To create the Tree, send a POST request to the Genealogies Tree resource. The documentation provides an example request for creating the tree.

Step 3: Add Data to the Genealogies Tree

There are a few different methods for adding information to the user's tree.

Working with the Genealogies Data Model

The Genealogies system uses a GEDCOM X data model consisting of Person, Relationship, and SourceDescription records.

The relationship model is different from the GEDCOM 5.x model consisting of Person and Family records. Two relationship types are used by GEDCOM X, namely http://gedcomx.org/ParentChild and http://gedcomx.org/Couple. The ParentChild relationship is a directional relationship, meaning that person1 represents the parent and person2 represents the child. From these two relationship types, you represent the relationships implied in the Family record individually.

For more information, see the GEDCOM X Conceptual Model documentation.

Strategies for Adding Data

You can either add persons and relationships one at a time, or add multiple persons and relationships in in bulk.

Adding persons and relationships one at a time

To add persons one at a time, send a POST request to the Genealogies Persons resource. Your request should include a GEDCOM X representation of the person, names, facts, etc. The response should provide an ID or URI of the person as a header.

To add relationships one at a time, send a POST request to the Genealogies Relationships resource. Your request should include a GEDCOM X representation of the relationship, including the identifiers to the related persons.

Example Requests:

• Create Genealogies Person
• Create Genealogies Relationship

Adding multiple persons and relationships in bulk

To add multiple persons at a time, send a POST request to the Genealogies Tree resource. The Genealogies Tree resource will accept a payload containing up to 100 persons represented in a GEDCOM X document. At this time, it is unclear how to retrieve the IDs for each of the persons created. This is an open issue and will be addressed by FamilySearch engineers.

To add multiple relationships at a time, send a POST request to the Genealogies Tree resource. It is advised to add all persons to the the tree prior to adding the relationships, so that you have identifiers for all persons represented in the requests. Relationship IDs are composed of the IDs of the persons involved in the relationships.

Example Requests

• Adding persons (TODO)
• Adding relationships (TODO)

Step 4: Update Persons and Relationships

As person data changes in your application, you will need to keep the user's data in sync with the tree found in the Genealogies system. The Genealogies API supports additions and deletions. If the same fact value is written twice, ((TODO: does it ignore the new one or update the timestamp?)).

TODO: Information on Relationship updates.

The strategy for keeping the data up to date depends upon the capabilities of your system.

Change Tracking Method

If your system is able to track individual changes in the form of a change log, then the process to keep the Genealogies Tree up to date is a matter of replaying the same changes on the remote tree.

• If a new person with new relationships was added to the local tree, your application would add the new person with the new relationships to the remote tree.
• If a new fact was added on the local tree, the new fact could be added to the person in the remote tree.
• If a fact was changed on the local tree, the previous fact would be deleted and the new fact added.

Compare and Modify Method

If your system does not keep track of changes, then the best way to keep in sync is to compare your data with what is in the Genealogies system and to calculate the difference.

One approach for doing this would be to create a GEDCOM X representation of the person and to compare that GEDCOM X representation to the GEDCOM X person read from the Genealogies system. As you develop this method, it may be helpful to test your comparison algorithms by following these steps:

1. Create a GEDCOM X document representing your local person. Let's call this gx1.
2. POST this person to the Genealogies API. You will receive back the ID for this person.
3. GET the person from the Genealogies API. Let's call this gx1'.
4. Compare gx1 to gx1'. Your comparison algorithm should indicate that they are the same.

Step 5: Get Matches

The last step in this process is to get matches (or hints) from the Genealogies API. The match resource will support the ability to read matches for both Family Tree persons as well as historical records.

Jimmy, we now have a way to get the IDs for the persons created back. When the endpoint is hit the response will be a GedcomX document with a list of SourceDescriptions, one for each person created. Each source description will have as its ID the id of the person element passed in (that caused the person to be created) and an Ark for the person that was created. In this way the client will be able to associate IDs for person in the client system with the Ark in Genealogies.

I've created a Postman collection with sample requests. This will continue to build out and refresh as I continue to work with it.