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

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_token query parameter is used for <img /> tags.
  • 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:

Change Language
Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.