FamilySearch Java SDK

About

This SDK is not longer officially supported.

The FamilySearch Java SDK is developed as an extension to the GEDCOM X Java library, which is a full implementation of the GEDCOM X Specification Set. This is because the FamilySearch API is an implementation of the GEDCOM X RS Specification, plus some custom FamilySearch extensions.

This Java SDK serves as the reference implementation for other SDKs.

Coordinates

The FamilySearch Java SDK is provided via a Maven repository structure. Most Java-based build systems (Ant, Maven, Gradle, etc.) have support for Maven repositories. The official Maven repositories are generously hosted by CloudBees. Following are some snippets of what the dependency declarations might look like in some of the most common build systems.

To find the latest version of the libraries, read the Maven Metadata and use the "release" version.

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>org.gedcomx.extensions.familysearch</groupId>
      <artifactId>familysearch-api-client</artifactId>
      <version>${gedcomx.version}</version>
    </dependency>
    ...
  </dependencies>
  ...
  <repositories>
    <repository>
      <id>gedcomx-release-repo</id>
      <name>GEDCOM X Release Repository</name>
      <url>https://repository-gedcom.forge.cloudbees.com/release/</url>
    </repository>
  </repositories>
  ...
</project>
            

<ivysettings>
...
  <settings defaultResolver="chain"/>
  <resolvers>
    <chain name="chain">
      <ibiblio name="central" m2compatible="true"/>
      <ibiblio name="gedcomx" m2compatible="true" root="https://repository-gedcom.forge.cloudbees.com/release/"/>
    </chain>
  </resolvers>
...
</ivysettings>
            

<ivy-module>
...
  <dependencies>
    ...
    <dependency org="org.gedcomx.extensions.familysearch" name="familysearch-api-client" rev="${gedcomx.version}"/>
    ...
  </dependencies>
...
</ivy-module>
            

...
repositories {
  maven {
    url "https://repository-gedcom.forge.cloudbees.com/release/"
  }
}
...
dependencies {
  runtime group: 'org.gedcomx.extensions.familysearch', name: 'familysearch-api-client', version: gedcomxVersion
}
...
            

...
repositories.remote << 'https://repository-gedcom.forge.cloudbees.com/release/'
...
compile.with transitive('org.gedcomx.extensions.familysearch:familysearch-api-client:#{gedcomx-version}')
...
            

Use

The Java SDK extends the GEDCOM X RS Client. In addition to the base functionality of the GEDCOM X RS Client, the SDK provides additional model classes, convenience classes, and methods to support FamilySearch-specific functionality.

The FamilySearch API uses hypermedia as the engine of application state and so using a client feels like browsing the web. As such, the SDK feels like using a screen scraper. The process can generally be summarized as follows:

1. Read the "Home" Collection
   Web sites have a "home page". The FamilySearch API has "home collections". Examples of collections include the FamilySearch Family Tree, FamilySearch Memories, and FamilySearch Records.
2. Follow the Right Link
   You get stuff done on a web site by following links to where you want to go. Ditto for the FamilySearch API.
3. Follow the Right Link
   Follow more links to get more stuff done.

Examples

For a set of examples of how to use the SDK, refer to the README.

Build

The FamilySearch Java SDK is developed as an extension to the GEDCOM X Java library. See the README for information about how to build the SDK from source.

Issues

Issues can be submitted issues using the issue tracker. Better yet, create a pull request.