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

2021 - Q2 Newsletter

Update July 14,2021 The release date for the experiment "search.return.enhanced.gedcomx" has been confirmed for release to production on Oct 5, 2021.

Update July 14,2021 The security policies and ciphers for the TLS update are different based on the domain referenced. FamilySearch uses AWS policy TLSv1.2_2019 for www.familysearch.org and ELBSecurityPolicy-FS-1-2-Res-2019-08 for api.familysearch.org. If your https security library throws errors, you will want to refer to these documents.

Note To add or remove an email address from the FamilySearch developer notification list, please contact devsupport@familysearch.org

This edition will cover the following topics:

Scheduled Maintenance

TLS 1.1 Removal

On May 7, 2021, you should have received the following notification regarding an important security update for TLS 1.1. This change is already effective in Beta and will be released to Production on Monday, July 12, 2021.

According to the December 2020 Developer Newsletter, we noted that support for TLS 1.0 would be removed. As TLS 1.1 is also considered a legacy protocol, FamilySearch will be removing support for TLS 1.1 as well. This change is scheduled for the maintenance update on Monday, July 12, 2021. To enable adequate testing, support for TLS 1.1 will be removed from the Beta environment on June 1, 2021.

Moving forward, FamilySearch will be following this maintenance plan for TLS security upgrades:

  1. In future quarterly developer newsletters, we will note the current industry standard for Transport Layer Security. Today it is TLS 1.3, which has been available since 2018.
  2. FamilySearch will support the current industry standard and one major release prior. For now this is TLS 1.3 and 1.2.
  3. During planned maintenance updates, FamilySearch will remove support for earlier versions of TLS in order to follow industry security protocols. Partners are encouraged to upgrade their security libraries regularly to avoid potential security issues as well as to continue to use the FamilySearch API.

FamilySearch Framing Prevention

As FamilySearch strives to increase application security and to follow industry best practices, we are planning a change to the headers on the www.familysearch.org site to prevent framing. This change would protect FamilySearch patrons from malicious sites attempting to trick patrons into performing unauthorized actions by overlaying a malicious page with the FamilySearch site. This technique is similar to the practice of phishing and is more commonly known as clickjacking.

The plan is to implement 2 changes in the headers similar to the following:


    X-Frame options: DENY
    Content Security Polity: frame-ancestors ‘none’
  

In order to provide partners enough time to test for this change, this security update will take place on beta.familysearch.org on July 12, 2021. We encourage you to test your site on Beta to prevent service interruptions. The change will roll out to production on October 11, 2021.

Please note: this may also affect applications which use embedded browsers that reference familysearch.org. Please confirm that your application is working as expected once this has been released to Beta.

503 Retry-After Header Response Update

Traditionally a 503 Service Unavailable response indicates that there was an internal issue preventing the service from responding. However, this error code does not indicate when the request can be resubmitted. An update to the 503 http responses for all FamilySearch API requests was released to Production in March 2021. Where possible, a new Retry-After header indicates when that service will be available again.

The 429 Throttling response has always included a Retry-After header. You should adjust how your application reacts to the new 503 Retry-After response in a similar manner if it is available. Please refer to the Throttling Guide for details on how your application should respond in these cases.

2021 Changes

Change to Search Results

The release for data changes to search results previously announced in March 2021 were delayed. These changes are now available in the Beta environment. This includes changes to the following:

  1. Person Names
  2. Person facts/fields/identifiers
  3. Person display information
  4. Relationships
  5. SourceDescriptions
  6. Places/Fields/Links

Please use the following experiment header. The final release to Production is anticipated for October 2021.


    search.return.enhanced.gedcomx
  

[UPDATE] OAuth 2.0 Changes for Desktop and Mobile

As announced in the March 2021 Developer Newsletter, the enhancement for long-lived refresh tokens is now available in each server environment. Please note that your app key must be configured on the server to request refresh tokens, so please send a message to devsupport@familysearch.org if this has not already been done. To request a 90-day refresh token, your application can pass a new scope parameter offline_access on the authorization request. Example request:


    https://ident.familysearch.org/cis-web/oauth2/v3/authorization
      ?response_type=code
      &scope=openid%20offline_access
      &client_id=a02j000000KTRjpAAH
      &redirect_uri=https://example.com/auth/
  

For more details on these refresh tokens and the transition away from Password Flow authentication, please refer to the following documentation:

All applications that have previously completed the Compatibility review for Authentication can be released with updated OAuth 2.0 code to Production at any time. The Password Flow authentication has been deprecated and support for this method will be removed by the end of 2021.

FamilySearch GEDCOM 7.0 Released

At RootsTech 2020, FamilySearch launched an effort to create a new version of GEDCOM based on the 5.5.1 version that would include: 1) new expressivity, flexibility, and compatibility; 2) zip packaging of associated images and other files with the related GEDCOM file; and 3) public access using a GitHub repository. Many industry software providers and key influencers participated, and the initiative concluded May 15, 2021.

FamilySearch GEDCOM 7.0 is the outcome of those efforts and includes the following new enhancements:

  • Zip packaging capabilities for photos and files have been added.
  • Notes have been expanded for more versatile use and styling of text.
  • Tools, sample files, sample code, and self-testing guides are included.
  • The FamilySearch GEDCOM specification and any code available from FamilySearch based on the specification is subject to the terms and conditions of the Apache License, Version 2.0.
  • Ambiguities in the GEDCOM Version 5.5.1 specification have been removed.
  • A public GitHub repository generates maintenance requests and on-going discussions about future features.

Technical information, specifications, tools, and guides can be found at GEDCOM.io.

Change Language
Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.