api best practices
DESCRIPTION
Ten Tips on the FamilySearch Partner API.TRANSCRIPT
BEST PRACTICESand what things to avoid
Sometimes the specification is misunderstood, or relevant parts of the specification are missed or not documented well.
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 GETUse Content-Type for a POST and PUT
Examples
GET /platform/tree/ancestry.xml?person=PS11-234
VS.
GET /platform/tree/ancestry?person=PS11-234Accept: application/x-fs-v1+xml
Tip #2
For the media-type header, use the version media type instead of “application/xml” or “application/json”
Example
Accept: application/x-fs-v1+xml
Accept: application/x-gedcomx-v1+xml
Example
Tip #3
List media types using commas
Example
Accept: application/x-gedcomx-v1+xml, application/atom+xml,application/xml
Tip #4
Use the Authorization header instead of the access_token stringparameter
Authorization: Bearer {access_token}
Example
Authorization: Bearer USYSblahblahblahfsglobal.net
Tip #5
Access tokens expire after 1 hour of inactivityor after 24 hours
Whichever comes first
Tip #6
Watch out for conflicting cookies between sandbox and production
Example: access token cookie
Tip #7
Use the Warning header to understand errors from FamilySearch.
e.g.Warning: blah blah blah
Tip #8
Watch for pending modifications athttps://familysearch.org/platform/pending-modifications
Example
Tip #9
Use the “X-FS-Feature-Tag” Header
API Evolution Guide
Dealing with Change
API Evolution Guide
Changes regarding the protocolChanges regarding resourcesChanges regarding resource representations
Changes Regarding Protocol
When the FamilySearch API is using HTTP insufficiently or incorrectly
Changes Regarding Resources
Resources are units of information• Person in the tree• Source description• Photo• Search results
Changes Regarding Resources
Resources change because:User - merged duplicate peopleSystem – resource in database is denormalized
Resource Representations Changes
GEDCOM X for genealogical dataExtensions for custom and proprietary resources
Resource Representations Changes
Data format changes -adding propertiesremoving propertieschanging the datatype of a property value
Changes
Compatible ChangesIncompatible Changes
Compatible Changes
Examples:Additive ChangesSemantically-Equivalent
Incompatible Changes
Examples:Deletion of propertiesChanges to the datatypes of property values
Rollout of Incompatible Changes
Pending Modificationshttps://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
Example
X-FS-Feature-Tag: remove-identity-v2-login,birth-date-not-considered-death-declaration
Tip #10
Use Hypermedia to drive your application state
Reason• In case of compatible changes, your client is:
• More adaptable• More Robust • More Maintainable• Less Pain
Reason• The API makes compatible changes without breaking the
clients• The client detect changes to resources through the
hypermedia