2018 - July Newsletter
Important Announcements
Please be aware that several deprecated API resources will be turned off beginning in September. See the Upcoming September Changes below.
June Changes in Review
Transition from familysearch.org to api.familysearch.org
API requests to familysearch.org began redirecting to api.familysearch.org. Please be advised that this redirect is temporary and will be turned off in September.
GEDCOM X POST for Person Matches Resource
A new feature was released on the Person Matches Resource providing more accurate match results. This feature provides the ability to describe the person, parents, spouses, and children with a GEDCOM X document. The GEDCOM X document is to be sent through the POST method to the Person Matches Resource.
Deprecation of GET for Person Matches Resource
Please note that with the release of this improved match capability comes the deprecation of the GET method on the Person Matches Resource. It is strongly advised to migrate to the new POST method as quickly as possible. The GET method will continue to be supported for the near term, but watch for a future announcement regarding the retirement of the GET method.
Upcoming September Changes
Warning The following are changes that if ignored, could potentially break your integration.
Turning off deprecated API resources
Beginning September 18 the following API resources may be 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 code 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 |
API Integration Tips
Handling of API Responses
As your integration with the FamilySearch API processes responses, please make sure that it is prepared to handle the various HTTP status codes that may be returned by the API. In particular, a few status codes to focus on are the 429 and 401 status codes.
The 429 status code represents a rate-limited response. This means that your application has used up its allocated processing time and needs to wait a given interval of time before trying again. The throttled response should contain special headers indicating how many seconds to wait before you try again. Please make sure your integration does not immediately attempt a retry without waiting the appropriate time. Please see the Throttling guide for more information.
The 401 status code represents a request containing a missing or invalid access token. Please be aware that an access token will expire after it has been inactive for a certain period, or when it has reached its max lifespan. When you receive a 401 status code, your integration will need to reestablish a new valid access token. For more information see the Access Token Resource documentation.
Warning Headers
The API returns Warning headers intended to report on integration best practices, provide additional error troubleshooting information, and inform of deprecations. It may be useful to you as a developer to develop a way to log or display these warning messages in a way that doesn't interfere with your end customer experience but in a place that you as a developer will see them.