Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser

Skip main navigation

2018 - September Newsletter

This edition will cover the following topics:

Upcoming December Changes

⚠️ Warning: The following contains changes that if ignored, could break your integration!

Deprecation and Retirement of Redirect Resource

The Redirect Resource (/platform/redirect) has now been deprecated. Beginning December 11, 2018, the Redirect Resource may be turned off. If your integration provides hyperlinks to tree person pages, your integration should use Persistent Identifier URLs. If your application uses the Redirect Resource to link to other pages on FamilySearch.org, you should update the links to point directly to the respective pages without using the Redirect Resource. Important information regarding the best practices for linking to FamilySearch.org is found in the API Integration Tips portion of this newsletter.

Descendancy Resource Changes

Beginning December 11, 2018, the Descendancy Resource will be changed to no longer support the spouse parameter and will change the numbering scheme for the first spouse. This change is available to test by using the Pending Modification tag remove.descendancy.spouse.filter.

Discontinued Spouse Parameter

The Descendancy Resource spouse parameter has been deprecated and will no longer be supported. When this change goes live in December, all spouses and descendants will be returned on all requests.

Spouse Numbering

The first spouse will begin numbering with -S1 instead of -S.

descendancy number description
1 The root person.
1-S1 The (primary) spouse of the root person.
1-S2.2 The second child (via the second spouse) of the root person.
1.2.5-S1 The primary spouse of the fifth child (via the primary spouse) of the second child (via the primary spouse) of the root person.

Beta Environment Refresh

Please be aware that the Beta environment will be unavailable for use beginning November 26 and will be offline for approximately two weeks. This is due to the data being refreshed in that environment to more closely reflect the Production environment data.

New Features and Updates

We are excited to announce a few updates that can be used to improve the user experience of your integration. These features include:

  • New My Relationships Resource
  • OpenID Connect Support
  • Support for Sources on Living Persons
  • A new Portrait model

New My Relationships Resource

The new My Relationships Resource provides a way to query how the authenticated user is related to another person in the tree. This feature is currently in its Prototype release phase. This means that the API is under active development. Because changes, including incompatible changes, are likely to occur, developers are encouraged to provide feedback on the design and usefulness of the API.

Depending upon feedback received, this new feature could be released to a stable Production release phase as early as December.

For more information regarding release phases, see the "Introducing New API Components" section of the API Evolution Guide.

OpenID Connect Support

The FamilySearch API now supports OpenID Connect, which is a simple identity layer on top of the OAuth 2.0 protocol. OpenID Connect brings the following benefits to your user experience.

OpenID Connect enables your users to take advantage of their existing FamilySearch.org authenticated session. If the user is logged in on FamilySearch.org, it will not require the user to log in again. If the user was not previously logged in on FamilySearch, the process of logging in to obtain an access token will also initiate a FamilySearch.org session. This enables the user to follow links to the website without needing to re-authenticate for as long as the website session remains active.

Another benefit is that the POST to the Access Token Resource will return an Access Token and an Identity Token. The Identity Token contains profile information for the user. This can simplify your integration by eliminating the need for a subsequent call to the Current User Resource.

To use OpenID Connect with your integration, add the scope=openid query parameter to your Authorization request. Additional scope values are documented in the Identity Scopes section of the Authentication Guide. If you encounter any errors when activating this feature, please email Developer Support.

To learn more about using OpenID Connect, see the OpenID Connect Specification.

Sources on Living Persons

The Family Tree web experience now supports attaching sources to living persons. This functionality was previously available through the API. It is important to note that the Source Description is public even though the living Person is still private to the user. We recommend that you inform your users that all sources are public even when attached to living persons.

Portrait Behavior Change

The Family Tree has changed the behavior of a tree person's portrait image. Previously, users were able to set a preferred portrait for any given person in the tree. The selected portrait setting was specific to the user and other users could have a different portrait setting. Under the new simplified model, when a user changes a person's portrait, the change applies for all users. The API interface for requesting a person's portrait and for setting the portrait should remain compatible.

Please be aware that the delivery of the portrait image bytes will change in the future. The URL that will return image bytes will consist of a temporary, expiring URL. This means your application should not store the URL returned by the portrait request, but should always request the portrait from the API. This behavior will be made available in the Beta environment for testing prior to a release to production.

API Integration Tips

Linking to Pages on FamilySearch

FamilySearch.org is a dynamic website that changes frequently. It is possible that URLs for most website experiences could change at any given time.

Some resources such as Family Tree Persons, Record Images, Records, and Genealogy Persons need a way to be referenced in a persistent way. To address this need, Persistent Identifiers have been established for these resources. Persistent Identifiers are URLs containing a path beginning with /ark:/. Sometimes these are referred to as ARK URLs because they follow the ARK specification.

The use of a Persistent Identifier is the only supported method for linking to FamilySearch.org. This means that your users can follow a Persistent Identifier URL from your application and FamilySearch will redirect the user to the current location of the content if the content still exists, and the user has rights to view it.

Your integration can still link to other parts of the website, but at your own risk. There is no guarantee that non-persistent URLs will remain unchanged. Non-persistent URLs may change at any time and without warning.

For Family Tree Persons, you can find the Persistent Identifier in the following locations:

XML

<gedcomx ...>
      <person>
        ...
        <identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:KW8W-RF8</identifier>
        ...
      </person>
    </gedcomx>
    

JSON

{
      "persons" : [{
        ...
        "identifiers" : {
          "http://gedcomx.org/Persistent" : ["https://familysearch.org/ark:/61903/4:1:KW8W-RF8"]
        }
        ...
      }]
    }
    

See the Persistent Identifiers guide for more information.

If you would like your traffic to FamilySearch to be recognized, you may pass a Campaign ID as a cid query string parameter on the URL. This simply identifies the traffic as being referred by your application. For more information on Campaign IDs see the guide on Linking to FamilySearch Pages.

HTTPS Connections

It is important to ensure your integration stays current with the latest SSL/TLS libraries to minimize security vulnerabilities and to maintain compatibility with FamilySearch systems. FamilySearch currently supports TLS v1.1 and v1.2. It is recommended that your integration connect using TLS v1.2.

September Changes in Review

Turning off deprecated API resources

Beginning September 18, the following API resources have been turned off, resulting in a 404 status code response.

API calls to familysearch.org will no longer redirect to api.familysearch.org. Please make sure your integrations are updated to point directly to api.familysearch.org or your integration will no longer function.

API Resource Documentation Resource Path Link rel Migrate To
Discovery /platform/app-meta
/.well-known/app-meta
Collections Resource
or
Family Tree Collection Resource
Person with Relationships /platform/tree/persons-with-relationships{?access_token,person,persons} "person-with-relationships-query" Person Resource
Relationships to Parents /platform/tree/persons/{pid}/parent-relationships "parent-relationships-template" Person Resource
Relationships to Spouses /platform/tree/persons/{pid}/spouse-relationships{?access_token,persons} "spouse-relationships-template" Person Resource
Relationships to Children /platform/tree/persons/{pid}/child-relationships{?access_token,persons} "child-relationships-template" Person Resource
Person Source References /platform/tree/persons/{pid}/source-references{?access_token} "person-source-references-template" Person Resource
Person Discussion References /platform/tree/persons/{pid}/discussion-references{?access_token} "person-discussion-references-template" Person Resource
Person Memory References /platform/tree/persons/{pid}/memory-references{?access_token} "person-memory-persona-references-template" Person Resource
Change Language
Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.