2022 - Q2 Newsletter
Note To add or remove an email address from the FamilySearch developer notification list, please contact devsupport@familysearch.org
This edition will cover the following topics:
Scheduled Maintenance
There are no maintenance releases planned for 2022 – Quarter 2.
2022 Changes
There are no API enhancements scheduled to be released for 2022 – Quarter 2.
Best Practices
HTTP Response Status Codes
Critical to the request and responses of web services are the standard list of HTTP status codes and the HTTP headers associated with those responses. FamilySearch has strived to adhere to industry standards regarding this interaction but has had to make a few minor changes over the years because of the unique and complex architecture associated with family tree data. Just in the past few weeks some Partner applications have overlooked some of the critical details of these HTTP responses and have caused issues not only for their own users but also for others in this shared environment. We recommend each developer take a fresh look at how the following response codes are handled.
301 Moved Permanently
Web based applications and some resource libraries handle redirects automatically. This occurs commonly when
the requested data has been changed and the previous version is no longer valid. When the value for
X-entity-forwarded-id is included in the Location header, it shows an updated personal identifier
(PID) that should be updated in the user’s local data rather than expecting to always redirect through a
series of deleted records each time that a bit of data is requested for that record. (Over time with lots of
changes occurring, there may be quite a few redirects that occur.) Example Location header:
HTTP/1.1 301 Moved Permanently
Content-type: application/x-gedcomx-v1+json
X-processing-time: 3
Vary: Accept,Accept-Language,Accept-Encoding,Expect
X-entity-forwarded-id: PPPJ-MYZ
Content-location: /platform/tree/persons/PPPJ-MYZ
Date: Sun, 03 Apr 1836 10:00:00 GMT-5
Cache-control: no-transform, must-revalidate, max-age=0
Location: https://api.familysearch.org/platform/tree/persons/PPPJ-MYZ
Transfer-encoding: chunked
303, 307 Temporary Redirect
These status codes reflect a possible temporary state, such as the current user person, and local data should not be updated to reflect the return URL. This indicates a likelihood of the original requested data reverting rather than staying at the current redirected value. Following the redirect is the best course of action each time it is encountered.
400 – 499 status codes
Status codes in this range reflect an error returning the desired data. It may be a problem with the request
itself 400, an unauthorized request for access 401,403, etc. In most of these cases, an error message
will need to be displayed to the user and the request should not be retried unless the active session has
changed. Retrying the same request in the same session will always yield the same error response. For
example, if the existing user succeeds in authenticating after a failed login, establishes a new session
after a timeout, or a different user authenticates to establish a new session, retrying the request may
result in potentially a different response. After the current 4XX level response has been resolved and if
the current session is still valid, additional requests that may be queued locally may still be submitted.
One exception to retrying the request in the same session is in the case of a 429 status code (Too many
requests) when the system has needed to throttle the requests for the current user. When the Retry-After
header is consulted and the delay specified is followed, the same request may succeed when previously it has
failed. The application may choose to inform the user how long the delay has been set for and to allow the
user to cancel the current operation rather than repeating the same request indefinitely or for an
unexpected duration. Please refer to the Throttling Guide for more
details. Example Retry-After header with Retry-After specified in seconds:
Server: Apache-Coyote/1.1
Retry-After: 5
X-PROCESSING-TIME: 200
Content-Type: application/x-fs-v1+json
Transfer-Encoding: chunked
Date: Thur, 01 May 2014 18:55:13 GMT
Connection: close
500 - 599 status codes
Status codes in this range reflect system problems in either processing the request or in being able to return the response. The user should be informed that a system problem has occurred, but the request should generally not be immediately retried and additional requests that are queued for processing should also be cancelled. Even if a server is automatically rebooted due to an internal error, it will take some time before any requests can be handled again.
One exception to automatically retrying the request is for 503 (Service Unavailable). If the 503 response
includes a Retry-After header, like the 429 throttling response, following the delay and repeating the same
request may result in success once server resources are again available. If this header is not
included in the response, a 503 response should be treated like a 500 (internal server error) and the user
should be informed that system resources are not currently available. The user may choose to execute the request again when they feel
a sufficient delay has passed.
Language Tags
For several years FamilySearch FamilyTree has supported the use of language tags to provide improved control over the storage of data in multiple languages. But as automated processing and handling of this data continues to develop, the requirement for specifying the correct language tags for that data will change from optional to required. When it is enforced, any requests with data with the incorrect language tag will return an error when it is submitted. For example, storing Chinese characters as English text. There is currently no timeline when these requirements will be enforced. However, with data in multiple languages becoming more commonplace, all applications should ensure that language tags in FamilySearch data are recognized.
If all data elements in a request to the FamilySearch API will be of the same language, a default language
can be set in locale for the >Accept-Language header, which will apply to all values not specifically
overridden in a NameForm object. If a
request includes multiple language tags, the lang value for each NameForm should be specified to ensure
accuracy for all Conclusions.
Why would you want to specify multiple language tags for a Gedcom-X object? This concise specification provides the ability transcribe the text into multiple written languages while maintaining the correct attributes for each value. For example, a given name such as “蒋宋美玲” may be easily pronounced by someone recognizing these characters. Formally defining the language tag as Chinese may allow FamilySearch algorithms to provide a Romanized form of these characters as “Jiang Song Meiling” that may be pronounced by English speakers. This system may also be able to sort lists of names, following the linguistic rules of that language tag. A Person that has source data from multiple countries, languages, and places will need to have each of these Conclusions recorded with the appropriate language tag.