-
Notifications
You must be signed in to change notification settings - Fork 9
RS Developers Guide
The GEDCOM X RS model provides the data structures that are used for defining a RMM level-3 REST API for genealogical data. The definition of a standard API for working with genealogical data enables consumers of genealogical data to be compatible with different providers who are compatible with the standard. The potential is to be able to write genealogy "apps" work the same way for all data providers who implement the standard.
Representational State Transfer (REST) is a set of architectural principles and constraints that can be applied to a Web service API in order to promote a well-defined, scalable, uniform interface. The details of REST are beyond the scope of this document, but the Wikipedia article on REST is a good place to start.
In conformance to RESTful principle of Hypermedia As The Engine Of Application State, the means by which
the API is defined is by using hyperlinks which describe the "state" of the application being
consumed. Each link can be "followed" using a small, well-known set of operations (HEAD, GET, PUT, POST, DELETE) that are used to "drive"
the application state. Each link describes its "relationship" to the current application state by using a well-defined set of values
so that API consumers can predict the results of following that link.
Therefore, the definition of an API that conforms to RESTful principles includes the following things:
- An application "entry point".
- A well-defined set of "representations" that supply links that describe the application state.
- A well-defined set of "relationship" values that describe the nature of the links.
The application entry point is a URL that supplies a representation of the application state using a set of links. Consumers of the API can then drive the application state using those links. The entry point URL should be the only piece of unique information that is specific to each different application.
A GEDCOM X application entry point supplies a representation of the links element.
The "representations" applicable to a GEDCOM X application are simply the representations of GEDCOM X resources as defined by
each model. Note that links to related resources are supplied using the rdf:resource attribute
(see the Developers Guide for more information), but resource references are not always adequate to drive application state.
For example, a relationship resource may reference the person resources that are part of the relationship, but consumers
of a GEDCOM X application also need to know how to edit the relationship by changing its person resources. A separate link
must be described so that consumers know how to drive the application into the desired "state".
The links to the application state are supplied using the link element, which defines an
href attribute specifying the link URL and a rel attribute specifying the nature of the link. By analysing the link
elements on each representation, a consumer of the API can know what options are available for driving the state of the
application.
GEDCOM X defines a set of known values for link "relationships". The common set of link relationship values are defined here. Additional link relationship values are defined by each application profile.
todo: specify link relationships
GEDCOM X organizes it's application-level specifications into "profiles". An application profile is just a group of resources, links, constraints, recommendations, and use cases that describe how a conforming application behaves. When an application claims conformance to a profile, it is effectively claiming that it supports all of the resources, links, constraints, and recommendations of the profile.
The core record profile defines an application that provides basic functionality for reading and writing data that is extracted from records, such as physical artifacts or online images.
The core conclusion profile defines an application that provides basic functionality for reading and writing conclusion data, such as is used to build a pedigree.