2020 - Q3 Newsletter

This edition will cover the following topics:

• 2020 - Q3 Newsletter
  • Scheduled Maintenance
  • Upcoming November Changes
  • Important API Best Practices
  • Upcoming 2021 Changes
    • Major Change to Authentication for Desktop and Mobile Apps

Scheduled Maintenance

Several infrastructure upgrades have been applied to the Integration and Beta environments to stay current with critical security updates. Internal testing has been completed to confirm that all service endpoints continue to be compatible with previous versions. If you have concerns about the compatibility of your application(s) with these updates, please test your product against the Integration and/or Beta environments by the end of August.

Upcoming November Changes

There are no changes scheduled to be released in November that will cause breaking changes to your application. However, if you develop a desktop or mobile application, we strongly encourage you to begin looking at the upcoming 2021 changes.

Important API Best Practices

We encourage the following best practices in utilizing the FamilySearch API. The Platform API will begin enforcing some of these automatically. Some deprecated practices will result in errors instead of data. For additional details and examples, see the HTTP Guide.

• Use the api subdomain for all http web service requests. api.familysearch.org is the correct subdomain to make all requests for the FamilySearch API. Requests to familysearch.org and www.familysearch.org are deprecated and support may be removed in the future.
• Use an Accept header. Suffix-based content negotiation has been deprecated. For example, support for appending .xml, .json, or .txt to the end of the URL may be removed in the future. Please use the Accept header for all content negotiation. If you make a POST request that is expecting a return, please use an Accept header.
• Use an Authorization header. ?access_token (and ?sessionId) will become deprecated.
  • An exception will be made for the portrait resource where the access_token query parameter is used for <img /> tags.
• Identify your application's version number with User-Agent header. This is important for native apps that require users to install or upgrade. See the Mozilla specification on User-Agent.
• Always use an authenticated session. Unauthenticated sessions are deprecated and support may be removed in the future. Requests without a valid session will return a 401 error.
• Get rid of old Pending Modifications. See the pending-modifications page. You can stop sending the pending modification headers after the change has been activated permanently. For example, you can now remove all generic-relationship related pending modification headers.
• Requests to the FamilySearch API are rate-limited on a per-user basis. For details and examples, see the Throttling guide. Please make use of the Retry-After header.
• 503 errors will begin returning a Retry-After header. If the Retry-After is present, please honor those conditions the same as you would a 429 response with Retry-After.

Upcoming 2021 Changes

Major Change to Authentication for Desktop and Mobile Apps

In an effort to increase the security of FamilySearch user data and to enable future options for user authentication, support of the OAuth 2.0 password flow will be discontinued. In place of the password flow, users will be directed to the FamilySearch Authorization page for authentication. Refresh tokens will be provided to reduce the frequency of user login prompts.

More information will be coming with specific details regarding the update. In the meantime, here is recommended reading that will help to prepare you for this change.

• AppAuth.io - Library for iOS, MacOS, Android, and native JavaScript
• OAuth 2.0 Simplified Book:
  • Chapter 6 "Mobile and Native Apps"
  • Chapter 15 "OAuth for Native Apps"
  • Chapter 17 "Protecting Mobile Apps with PKCE" (this also applies to desktop apps)
• Specifications: OAuth 2.0 for Native Apps, Proof Key for Code Exchange (PKCE)

We understand that this will be a significant change for mobile and desktop developers, and we will provide as much assistance as possible to help in this change. The retirement of the password flow is currently targeted for February of 2021.