Api best practices

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