HTTP

Methods

All HTTP operations are applicable to a resource: GET, PUT, POST, DELETE, HEAD, etc. However, for a given endpoint, the FamilySearch API may not support a particular HTTP operation, in which case a 405: Method Not Allowed response is provided. For example, POST is the only accepted HTTP operation on the Persons endpoint.

The documentation for each endpoint includes the valid HTTP methods. To retrieve information about other supported HTTP methods, use the HTTP OPTIONS method at runtime.

If your system is capable only of making GET or POST requests, you can use the X-HTTP-Method-Override header. This allows you to make a POST request, but indicates that you really mean to make a PUT. Example:

POST /tree/persons/12345
  X-HTTP-Method-Override: PUT

Accept Header

Each resource can be represented with different data formats. The Accept header is used to request a specific format. To get the XML representation of a Person resource:

GET /tree/persons/12345
  Accept: application/x-gedcomx-v1+xml

Or, to get the JSON representation:

GET /tree/persons/12345
  Accept: application/x-gedcomx-v1+json

The value application/x-gedcomx-v1+json identifies the data format (a.k.a. "media type") to be returned. The documentation for each endpoint includes a list of the valid data formats.

The media types application/xml and application/json are also valid, but if a new version of the resource (e.g. x-gedcomx-v2+xml) is provided at the same URI, the system will have to guess which version you want.

If you are unable to use the Accept header, the FamilySearch API provides a convenient alternative: you can append .xml or .json to the URI for each resource, as demonstrated following.

GET /platform/collections/tree.xml

FamilySearch Family Tree (XML)

GET /platform/collections/tree.json

FamilySearch Family Tree (JSON)

Authorization Header

Rather than putting the access token on the URI, the preferred way to provide the credentials is to include it on an HTTP header named Authorization. The value for the Authorization header is the string Bearer plus the access token returned when logging in to the system.

Authorization: Bearer {Token}