API Evolution

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 protocolChanges regarding resourcesChanges 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 ResourceCurrently, 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 ResourceAs 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:

Timing of new API Features

New API features will be rolled out as follows:Prototype will roll out on the quarterly schedule of March, June, September, and December. It will run for approximately 30 days from the date of the newsletter.Beta phase will begin after the 30 days of Prototype phase. It will last for approximately 60 days.Production phase will be rolled out at the end of the beta phase. It will also coincide with the quarterly release cycle. If we need to extend the prototype or beta phases, we may roll out to production outside of the quarterly release cycle.If a new API feature is replacing an existing feature, we will deprecate based on the quarterly release cycle.

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.DescriptionExamplesChanges in compliance with the HTTP specificationNew cache directives, using a new status code, new support for defined HTTP request and response headers, etc.Changes in compliance with the data format specificationsChanging 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 resourcesChanging 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:DescriptionExamplesIncorrect use of the HTTP specificationIncorrect status code, invalid characters in HTTP headers, etc.Removal of support of a required aspect of a data format specificationInvalid XML namespace, invalid references to other elements, etc.Error in the implementation of a data formatIncorrect 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 the potential for disruption to consumers 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.

Timing of API Changes

All backwards incompatible changes will be made on a quarterly basis. We have designated the first of March, June, September, and December as the times we will roll out these changes. Dates may vary a few days based on the release cycles of the engineering teams. All dates will be announced in the preceding newsletter.

Common Changes