1. The document provides tips for best practices when using the FamilySearch API, such as specifying the data type in headers rather than URLs, using specific media types, and handling errors and changes to resources. 2. It recommends using hypermedia to make clients more adaptable and robust to compatible changes by allowing them to detect changes through hypermedia links rather than rigid URLs or representations. 3. The API Evolution Guide section discusses preparing for and handling compatible and incompatible changes to the protocol, resources, and their representations.

1. BEST PRACTICES
and what things to avoid

2. Sometimes the specification is misunderstood,
or relevant parts of the specification are missed
or not documented well.

3. Tip #1
To specify the type of data returned from a call to the API,
avoid using .xml and .json on the URL.
Instead:
Use Accept header for a GET
Use Content-Type for a POST and PUT

4. Examples
GET /platform/tree/ancestry.xml?person=PS11-234
VS.
GET /platform/tree/ancestry?person=PS11-234
Accept: application/x-fs-v1+xml

5. Tip #2
For the media-type header, use the version media type
instead of “application/xml” or “application/json”

6. Example
Accept: application/x-fs-v1+xml
Accept: application/x-gedcomx-v1+xml

7. Example

8. Tip #3
List media types using commas

9. Example
Accept: application/x-gedcomx-v1+xml,
application/atom+xml,application/xml

10. Tip #4
Use the Authorization header instead of the access_token
stringparameter
Authorization: Bearer {access_token}

11. Example
Authorization: Bearer USYSblahblahblahfsglobal.net

12. Tip #5
Access tokens expire after 1 hour of inactivity
or after 24 hours
Whichever comes first

13. Tip #6
Watch out for conflicting cookies between
sandbox and production
Example: access token cookie

14. Tip #7
Use the Warning header to understand errors from
FamilySearch.
e.g.
Warning: blah blah blah

15. Tip #8
Watch for pending modifications at
https://familysearch.org/platform/pending-modifications

16. Example

17. Tip #9
Use the “X-FS-Feature-Tag” Header

18. API Evolution Guide
Dealing with Change

19. API Evolution Guide
Changes regarding the protocol
Changes regarding resources
Changes regarding resource representations

20. Changes Regarding Protocol
When the FamilySearch API is using HTTP insufficiently or
incorrectly

21. Changes Regarding Resources
Resources are units of information
• Person in the tree
• Source description
• Photo
• Search results

22. Changes Regarding Resources
Resources change because:
User - merged duplicate people
System – resource in database is denormalized

23. Resource Representations Changes
GEDCOM X for genealogical data
Extensions for custom and proprietary resources

24. Resource Representations Changes
Data format changes -
adding properties
removing properties
changing the datatype of a property value

25. Changes
Compatible Changes
Incompatible Changes

26. Compatible Changes
Examples:
Additive Changes
Semantically-Equivalent

27. Incompatible Changes
Examples:
Deletion of properties
Changes to the datatypes of property values

28. Rollout of Incompatible Changes
Pending Modifications
https://familysearch.org/platform/pending-modifications
HTTP Request Header
“X-FS-Feature-Tag”
value is a comma delimited list of labels from the
pending modification page

29. Example
X-FS-Feature-Tag:
remove-identity-v2-login,
birth-date-not-considered-death-declaration

30. Tip #10
Use Hypermedia to drive your application state

31. Reason
• In case of compatible changes, your client is:
• More adaptable
• More Robust
• More Maintainable
• Less Pain

32. Reason
• The API makes compatible changes without breaking the
clients
• The client detect changes to resources through the
hypermedia