API Evolution Guide

This guide is intended to provide an explanation of how the FamilySearch API evolves, how changes are communicated, and how developers can write software that effectively adapts to those changes.

Executive Summary
  • Changes to the API may occur with regard to the protocol, to API resources, or to resource representations.
  • Both compatible and incompatible changes may be applied to the API.
  • Versions of the API are not exposed on the URI.
  • Clients are expected to gracefully handle compatible changes to the API.
  • FamilySearch will roll out incompatible changes (and some compatible changes) using Pending Modifications.

Dealing With Change

The applications that FamilySearch develops are active, living systems. New features are added, old functionality is pruned, and bugs are fixed. While change is generally considered to be a good thing, it is often very difficult to manage. This is especially true for software developers who are particularly concerned with making sure that the software they produce is stable and functioning properly.

FamilySearch is acutely aware of the potential impact that any change to the FamilySearch API may have on your software. This guide is designed to document the following:

  • The philosophy that governs how change is implemented in the FamilySearch API.
  • The process by which change in the FamilySearch API is managed, communicated, and deployed.
  • The tools and mechanisms that are used to implement changes to the API.
  • The features available to developers that can be used to implement both backward-compatibility and forward-compatibility in software that consumes the FamilySearch API.
  • The expectations for dealing with change that API consumers should have of FamilySearch.
  • The expectations for dealing with change that FamilySearch has of its API consumers.
  • The common types of changes that occur in the FamilySearch API and how those changes are integrated.

The FamilySearch API Change Philosophy

A lot of effort has been applied to the FamilySearch API to align it with the principles of API design and best practices that have been tested and proven in the technology industry. Many of these principles and practices are built on the architecture of the World Wide Web and have been formalized by experts who have successfully applied that architecture to real-world highly-adaptable APIs.

As to how APIs evolve, changes can generally be placed into the following three categories:

  • Changes regarding the protocol
  • Changes regarding resources
  • Changes regarding resource representations

Changes Regarding the Protocol

The FamilySearch API is made available via the Hypertext Transfer Protocol (HTTP). HTTP defines what operations (e.g., GET, POST, DELETE) are available, how requests are made, and how responses are to be processed. This includes how status conditions are communicated, such as whether a resource is available, moved, deleted, or whether any errors are applicable.

Where possible, FamilySearch uses the mechanisms defined by the HTTP specification to communicate the state of the application. Developers are expected to write software that appropriately handles the conditions defined by HTTP. When the FamilySearch API is found to be using HTTP insufficiently or incorrectly, a correction will be made and rolled out in conformance with the change constraints defined below.

Changes Regarding Resources

The FamilySearch API is defined by the resources it provides. Resources are simply units of information, such as a person in the tree, a source description, a photo, or a set of search results. Each resource can be uniquely identified by one or more Uniform Resource Identifiers (URIs).

The state and lifecycle of a resource is maintained by the application that defines the resource. The FamilySearch API can be used to create, update, and delete resources. Some resources track a version or a last-modified timestamp that each might be exposed using standard HTTP headers (see the Caching guide). Some resources also have a change history so that users can determine the changes that have been applied to a resource over time.

Occasionally, resources move to different locations. Sometimes this occurs as a result of an action taken by a user, such as a merge of two duplicate persons in the tree. Sometimes this occurs as a result of changes in the server-side application, such as when a resource is migrated from one database to another, or when a resource in a database is denormalized. FamilySearch provides Hypermedia controls to communicate resource movements to clients. When a resource is moved, an appropriate HTTP redirect response code should be provided.

A Version of a Resource Is a Resource

Currently, FamilySearch does not maintain different versions of a resource. For example, if a person in the tree was at version 242 at the time that a user edited the person, bumping it to version 243, then FamilySearch doesn't provide you a way to read the previous version 242 of the person. However, for the sake of this document, it's important to note that if FamilySearch were ever to maintain different versions of a resource, each version would itself be a different resource. Using the previous example, version 242 of a person would be exposed as a different resource than version 243 of the person, and each version of the resource would have a distinct URI.

A Version of an API Is Not a Resource

As the FamilySearch API evolves, new versions of the API are released. FamilySearch maintains an awareness of API versions for internal purposes, such as to locate and identify bugs and to manage the deployment lifecycle. Consumers of the API should not have to be aware of the version of the API they are using.

At a practical level, different versions of the API are not exposed as different resources with different URIs. For example, if version 1.1 of the API exposes a person resource at /platform/tree/persons/MMM-MMMM, then version 1.2, version 2.3, or any other subsequent version of the API should expose the same person at /platform/tree/persons/MMM-MMMM and should not expose the person, for example, at /platform/tree/v2/persons/MMM-MMMM.

The benefits of this philosophy are self-evident.

  • Consumers of the API do not need to maintain an extra piece of data in code, nor do they need to be aware of API versions when reporting bugs or analyzing behavior of the API.
  • FamilySearch doesn't have to maintain a complex matrix of different API versions running simultaneously.
  • A good caching policy is supported because the number of URIs that resolve to the same resource is minimized, enabling greater scalability of the system.
  • Coupling between the client and the server is reduced, resulting in better alignment with well-established architectural principles.

For further reference, see Steve Klabnik's Designing Hypermedia APIs. Consider also Roy Fielding's treatment of the notion of client-server coupling in section 5.1 of his thesis on Representational State Transfer.

Changes Regarding Resource Representations

A data format has to be used to provide resources. As a convenience to consumers, FamilySearch makes available multiple representations for each resource. Genealogical data is represented using GEDCOM X, which defines both XML and JSON data formats. Where needed, FamilySearch has extended the GEDCOM X data formats to represent custom or proprietary resources. A specific representation of a resource should be requested by a consumer using the standard HTTP content negotiation mechanism, defined by Section 12 of the HTTP specification.

Data formats are defined by their respective specifications in terms of data types that have properties (sometimes referred to as "elements" and "attributes"). Each property is defined as a name and a value. A value is an instance of a data type. Changes to data formats include adding properties, removing properties, or changing the data type of a property value.

Representations of a resource may change as the FamilySearch API evolves. See below for a list of specific changes and the expectations associated with each change. Additive changes and changes that are defined by the data format specifications as semantically-equivalent changes are considered to be compatible changes, and clients are expected to gracefully adapt to these changes at runtime. Deletions of properties or changes to the data types of property values are considered to be incompatible changes to which FamilySearch should be held accountable in violation of the API contract. Where incompatible changes are necessary, the change must be rolled out in accordance with the change constraints defined below.

For further reference, see also RESTful Web APIs by Leonard Richardson and Mike Amundsen (O'Reilly). Copyright Leonard Richardson and amundsen.com, Inc., and Sam Ruby. 978-1-449-35806-8.

Introducing New API Components

The FamilySearch API can be logically grouped into sets of smaller APIs that provide common functionality. The boundaries of these API components are not always distinct, but they are usually described in terms of similar features and related use cases. Examples of these API components include the Sources API, the Discussions API, the Memories API, etc.

As new components are introduced into the FamilySearch API, the goal is to make them available in the form of a prototype so developers can provide early feedback. With each release, new functionality is added until the component arrives at a reasonable level of stability. At this point, developers are encouraged to write software that uses the new set of features and to report any bugs or design flaws. After a period of time, the component will be officially released.

The lifecycle of a component of the API is formalized in the following table.

Phase Description
prototype The API is under active development. Changes, including incompatible changes, are likely to occur. Developers are encouraged to provide feedback on the design and usefulness of the API.
beta The API is reasonably stable. Developers are encouraged to write code that uses the API and to report any bugs, inconsistencies, or design flaws. FamilySearch reserves the right to make incompatible changes, but will generally avoid doing so unless a fatal flaw in design is discovered.
release The API is finalized and will be changed only in conformance with the change constraints defined below.

How Change Is Applied

Sometimes changes need to be applied to components of the API that have been released.

Compatible Changes

Some changes are considered to be compatible changes.

Description Examples
Changes in compliance with the HTTP specification New cache directives, using a new status code, new support for defined HTTP request and response headers, etc.
Changes in compliance with the data format specifications Changing XML namespace prefixes, innocuous whitespace adjustments, new support for existing GEDCOM X data type properties, removal of support for optional GEDCOM X properties, new FamilySearch-proprietary extension elements, etc.
Moving resources Changing the location of the search resource, moving relationship list resources to the person resource, etc.

Compatible changes should not affect consumers of the API. Developers writing software in conformance with the established specifications shouldn't be affected by any compatible changes. Software that is written in a forward-compatible way is able to ignore any new data or functionality that is in conformance with the specifications. Software that is written in a backward-compatible way is able to adjust to any functionality or properties that are not defined as required by the specifications.

That said, FamilySearch recognizes that writing forward-compatible and backward-compatible software is a challenge and requires a good understanding of the supporting specifications. Sometimes the specification is misunderstood, or relevant parts of the specification are missed or not documented well. Sometimes developers use external tools and libraries that have bugs.

FamilySearch will use caution when applying compatible changes. Where there is reasonable potential for the change to disrupt consumers of the API, the change will be applied as a Pending Modification (see below), if possible.

Incompatible Changes

Occasionally, the FamilySearch API developers fail to anticipate requirements that surface after the release of an API. Other times, FamilySearch has simply made a significant mistake in the implementation of a specification. It is to be hoped that these cases are few, but it's not reasonable to expect that they won't happen.

Sometimes the only way to remedy a flaw is to introduce an incompatible change to the API. The following table provides a definition of incompatible changes.

Description Examples
Incorrect use of the HTTP specification Incorrect status code, invalid characters in HTTP headers, etc.
Removal of support of a required aspect of a data format specification Invalid XML namespace, invalid references to other elements, etc.
Error in the implementation of a data format Incorrect data type for a value of a property, invalid encoding of dates, etc.

When an incompatible change needs to be introduced, the change will be applied as an Pending Modification (see below).

Pending Modifications

The FamilySearch API Pending Modifications are provided as a mechanism to minimize to consumers the potential for disruption caused by changes to the API. Pending Modifications are intended to allow software developers a vehicle for trying out changes to the API and for making any adjustments needed to the software before the change becomes permanently active. Pending Modifications are designed to be available in all reference environments.

When a potentially disruptive change is identified, it is assigned a name and a date when the change will be permanently activated. As the change is being applied, FamilySearch engineers will implement the change with activation conditional on the presence of the name of the change in an HTTP request header called X-FS-Feature-Tag. If the name of the change is present in a comma-separated list, the change will be active for that HTTP request.

Developers writing software that consumes the API can add the appropriate request header, ensure that the software correctly adapts to the change, and make any needed adjustments. When the developer is satisfied that the software can adapt to the change on the date that it is permanently activated, the software can be released with the X-FS-Feature-Tag applied to each request. After the activation date, and at the leisure of the developer, an update can be applied that removes the X-FS-Feature-Tag header.

The list of currently-defined pending modifications is also made available as a resource in the FamilySearch API.

Common Changes

Change Designation Client Developer Expectations FamilySearch Expectations Anticipated Cost to Clients
A resource is moved. Compatible, potentially disruptive. Leverage the provided hypermedia controls to ensure your software can automatically adapt at runtime. Implemented as a Pending Modification and publicized by developer support. Medium
An HTTP response code is changed in compliance with the specification.

Compatible, potentially disruptive. Ensure HTTP compatibility to make sure your software can automatically adapt at runtime. Implemented as a Pending Modification and publicized by developer support. Low
A new data format (representation) is made available for a resource.

Compatible. Use HTTP content negotiation to ensure your software will continue to be served the correct data format. Not a Pending Modification. Made available when ready. Documented by the development team and publicized by Developer Support. Low
Support for an existing data format (representation) is removed from a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software is updated to not use the data format. Implemented as a Pending Modification. A reasonable end of life for the data format is determined and publicized by Developer Support. High
A new optional query parameter is made available on a resource. Compatible. Read the published documentation, add support for the new parameter if desired. Not a Pending Modification. Made available when ready. Low
A new required query parameter is removed from a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software is updated to provide the new parameter. Implemented as a Pending Modification. A reasonable activation date for the new requirement is determined and publicized by Developer Support. High
A new HTTP method is supported on a resource. Compatible. Ensure HTTP compatibility to make sure your software can automatically adapt at runtime. Not a Pending Modification. Made available when ready. Low
Support for an existing HTTP method is removed on a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software is updated to not use the method. Implemented as a Pending Modification. A reasonable end of life for the method is determined and publicized by Developer Support. High
A new property is provided on a JSON representation of a resource.

Compatible. Ensure your software is forwards-compatible and ignores any properties it does not recognize. Not a Pending Modification. Made available when ready. Low
Support for existing property is removed from a JSON representation of a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software does not fail when the property is removed. Implemented as a Pending Modification. A reasonable end of life for the property is determined and publicized by Developer Support. Depends on which property.
The type of the value of a property is changed on a JSON representation of a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software expects the new value. Implemented as a Pending Modification. A reasonable activation date for the change is determined and publicized by Developer Support. High
The order of properties is changed on a JSON representation of a resource. Compatible. Ensure JSON compatibility to make sure your software does not depend on the order of properties. Not a Pending Modification. Made available as needed. Low
Newlines and whitespace is added to a JSON representation to make it more readable. Compatible. Ensure JSON compatibility to make sure your software does not depend on insignificant whitespace. Not a Pending Modification. Made available as needed. Low
A new element or attribute is provided on an XML representation of a resource. Compatible. Ensure your software is forward-compatible and ignores any properties it does not recognize. Not a Pending Modification. Made available when ready. Low
Support for existing element or attribute is removed from an XML representation of a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software does not fail when the element or attribute is removed. Implemented as a Pending Modification. A reasonable end of life for the element or attribute is determined and publicized by Developer Support. Depends on which element or attribute.
The data type of an element or attribute is changed on an XML representation of a resource. Incompatible. Work with Developer Support well before the change is activated to ensure your software expects the new value. Implemented as a Pending Modification. A reasonable activation date for the change is determined and publicized by Developer Support. High
The order of elements or attributes is changed on an XML representation of a resource. Compatible. Ensure compatibility with the relevant XML format specification to make sure your software does not depend on the order of elements or attributes. Not a Pending Modification. Made available as needed. Low
Newlines and whitespace is added to an XML representation to make it more readable. Compatible. Ensure XML compatibility to make sure your software does not depend on insignificant whitespace. Not a Pending Modification. Made available as needed. Low
The xmlns prefix is changed on an XML representation of a resource.

Compatible. Ensure XML compatibility to make sure your software does not depend on the implementation of xmlns prefixes. Not a Pending Modification. Made available as needed. Low
Support for a new enumerated value (name type, fact type, etc.) defined by GEDCOM X is added. Compatible. Ensure your software is forward-compatible and ignores any enumerated values it does not recognize. Not a Pending Modification. Made available as needed. Low
Support for an enumerated value (name type, fact type, etc.) is removed. Incompatible. Work with Developer Support well before the change is activated to ensure your software does not fail when the change is applied. Implemented as a Pending Modification. A reasonable end of life for the enumerated value is determined and publicized by Developer Support. High
An existing business constraint is lifted. Compatible. Read the published documentation, make any adjustments to take advantage of the lifted constraint as desired. Not a Pending Modification. Made available when ready. Low
New business constraints are added. Incompatible. Work with Developer Support well before the change is activated to ensure your software is in compliance with the new business constraint. Implemented as a Pending Modification. A reasonable activation date for the change is determined and publicized by Developer Support. High