2020 - January Newsletter
This edition will cover the following topics:
Upcoming April Changes
ARK URL Changes
ARK URLs are persistent, meaning that an HTTP request to the URL will ultimately resolve to the resource. Requests may resolve directly or may be redirected.
The ARK should not be used as a permanent ID. If you are using the ARK as a permanent ID, only use the /ark: onward until the query string. The ID segment should remain permanent. The domain may change and should not be part of the identifier. This change may occur as early as April 7, 2020. For more information on the ARK standard, please see the specification published here.
Examples of Possible URL Changes
Old:
https://familysearch.org/ark:/61903/4:1:LZJW-C31
New:
https://ark.familysearch.org/ark:/61903/4:1:LZJW-C31
or
https://www.familysearch.org/ark:/61903/4:1:LZJW-C31
Example of ID portion of the URL
Given the following URL:
https://ark.familysearch.org/ark:/61903/4:1:KWJH-9QN?query_param=value
The ID portion would be /ark:/61903/4:1:KWJH-9QN
Ordinance Reservation Changes
An upcoming change will allow members of The Church of Jesus Christ of Latter-day Saints to reserve an ordinance that has been shared with the temple. These ordinances will have new status codes. The change will be managed through a pending modification to allow for a smooth transition.
New limits will be placed on the number of ordinances that a user can reserve. This will not remove existing reservations beyond the new limit, but will return an error when a user tries to reserve new ordinances that would exceed the limit.
More information is coming on both changes.
Important Best Practices
We encourage the following best practices in utilizing the FamilySearch API. Platform API will begin enforcing some of these. Some deprecated practices will result in errors instead of data. For additional details and examples, see the HTTP Guide.
- Use an Accept header - Suffix-based content negotiation will become deprecated. For example, appending .xml, .json, or .txt to the end of the URL will become deprecated. Please use the Accept header for all content negotiation.
- Use Authorization Bearer header - ?access_token (and ?sessionId) will become deprecated.
- An exception will be made for the portrait resource where the
access_tokenquery parameter is used for<img />tags.
- An exception will be made for the portrait resource where the
- Send in your application's version number with User-Agent header. See the Mozilla specification on User-Agent.
- Always use an authenticated session - unauthenticated sessions "may" go away, no valid session calls will become deprecated and return a 401 error.
- Get rid of old Pending Modifications. See our pending-modifications. 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 may be 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 error with Retry-After.
If you find an instance where these new protocols do not work for your situation, please let us know by sending an e-mail message to devsupport@familysearch.org
December Changes in Review
FamilySearch implemented the generic relationship update as discussed in the June 2019 Newsletter. The following documents explain the changes: