2020 - Q3 Newsletter
This edition will cover the following topics:
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 tofamilysearch.org
andwww.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 theAccept
header for all content negotiation. If you make aPOST
request that is expecting a return, please use anAccept
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.
- An exception will be made for the portrait resource where the access_token query parameter is used for
- 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 a429
response withRetry-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.