5. A Review
â Web service API
â A set of digital services and/or resources
made accessible over a computer network.
â HTTP
â Hypertext Transfer Protocol
â Defines how to make requests and interpret
responses.
6. A Review
â Resources
â The units of data making up the âmatterâ of
the API.
â The âsubjectâ of HTTP operations.
â Uniform Resource Identifier
â The locator for a resource.
â Includes a domain, path, query.
7. A Review
â Resource Representations
â How resources are serialized to a stream of
bytes.
â Often JSON and XML.
â a.k.a. âmedia typesâ or âdata formatsâ
â See âArchitecture of the World Wide Webâ
â http://www.w3.org/TR/webarch/
22. What If...
...new resources become available?
Available Resources
â Person
â Relationship
â Person Search
â ...
Available Resources
â Person
â Relationship
â Person Search
â Records
â Record
â Record Search
â ...
23. What If...
...an API changes domains?
https://familysearch.org/platform
https://familysearch.io/platform
24. What If...
...a resource moves?
/platform/tree/persons/12345/matches
/platform/tree/persons/12345/duplicates
25. What If...
...subresources are included
in their âparentâ resource?
/person/12345
Person
/person/12345/notes Person
Person
Notes
Source
References
/person/12345/sources
/person/12345
Person
+
Notes
+
Source References
26. What If...
â ...property order changes?
â ...some whitespace is added?
â ...XML changes namespace prefixes?
â ...caching policy changes?
â ...new resources are available?
â ...a resource moves?
â ...subresources are included in their
"parent" resource?
27. What If...
â ...property order changes?
â ...some whitespace is added?
â ...XML changes namespace prefixes?
â ...caching policy changes?
â ...new resources are available?
â ...a resource moves?
â ...subresources are included in their
"parent" resource?
49. What If...
...new resources become available?
Available Resources
â Person
â Relationship
â Person Search
â ...
Available Resources
â Person
â Relationship
â Person Search
â Records
â Record
â Record Search
â ...
50. What If...
...new resources become available?
Available Resources
â Person
â Relationship
â Person Search
â ...
Available Resources
â Person
â Relationship
â Person Search
â Records
â Record
â Record Search
â ...
Hypermedia
62. What If...
...subresources are included
in their âparentâ resource?
/person/12345
Person
/person/12345/notes Person
Person
Notes
Source
References
/person/12345/sources
/person/12345
Person
+
Notes
+
Source References
63. What If...
...subresources are included
in their âparentâ resource?
<html>
<head>
âŠ
<link rel=âstylesheetâ href=â...â/>
<script src=â...â></script>
âŠ
</head>
<body>
âŠ
</body>
</html>
64. What If...
...subresources are included
in their âparentâ resource?
<html>
<head>
âŠ
<link rel=âstylesheetâ href=â...â/>
<script src=â...â></script>
âŠ
</head>
<body>
âŠ
</body>
</html>
Embedded Links
(Hypermedia)
65. What If...
...subresources are included
in their âparentâ resource?
<html>
<head>
âŠ
<link rel=âstylesheetâ href=â...â/>
<script src=â...â></script>
âŠ
</head>
<body>
âŠ
</body>
</html>
<html>
<head>
âŠ
<style>
âŠ
</style>
<script>
âŠ
</script>
âŠ
</head>
<body>
âŠ
</body>
</html>
66. What If...
...subresources are included
in their âparentâ resource?
<html>
<head>
âŠ
<link rel=âstylesheetâ href=â...â/>
<script src=â...â></script>
âŠ
</head>
<body>
âŠ
</body>
</html>
<html>
<head>
âŠ
<style>
âŠ
</style>
<script>
âŠ
</script>
âŠ
</head>
<body>
âŠ
</body>
</html>
HTML says...
âOKâ
67. What If...
...subresources are included
in their âparentâ resource?
<gedcomx>
<person id=â12345â>
âŠ
<link rel=âsource-referencesâ
href=â/persons/12345/sourcesâ/>
<link rel=ânotesâ
href=â/persons/12345/notesâ/>
âŠ
</person>
</gedcomx>
68. What If...
...subresources are included
in their âparentâ resource?
<gedcomx>
<person id=â12345â>
âŠ
<link rel=âsource-referencesâ
href=â/persons/12345/sourcesâ/>
<link rel=ânotesâ
href=â/persons/12345/notesâ/>
âŠ
</person>
</gedcomx>
Embedded Links
(Hypermedia)
69. What If...
...subresources are included
in their âparentâ resource?
<gedcomx>
<person id=â12345â>
âŠ
<link rel=âsource-referencesâ
href=â/persons/12345/sourcesâ/>
<link rel=ânotesâ
href=â/persons/12345/notesâ/>
âŠ
</person>
</gedcomx>
<gedcomx>
<person id=â12345â>
âŠ
<source description=â...â/>
<note id=â...â>
âŠ
</note>
</person>
</gedcomx>
70. What If...
...subresources are included
in their âparentâ resource?
<gedcomx>
<person id=â12345â>
âŠ
<link rel=âsource-referencesâ
href=â/persons/12345/sourcesâ/>
<link rel=ânotesâ
href=â/persons/12345/notesâ/>
âŠ
</person>
</gedcomx>
<gedcomx>
<person id=â12345â>
âŠ
<source description=â...â/>
<note id=â...â>
âŠ
</note>
</person>
</gedcomx>
GEDCOM X says...
âOKâ
80. How To...
â Add a person to a collection.
â Search a collection for persons.
â Do a âfullâ person read.
â Upload an artifact to a collection.
â Edit the birth date of a person.
â Read the list of photos on a person.
â Delete a person.
81. How To...
Add a person to a collection.
â Read the collection.
â Find the link to the âpersonsâ of the
collection.
â POST the new person to that URI.
82. How To...
Add a person to a collection.
â Read the collection.
â Find the link to the âpersonsâ of the
collection.
â POST the new person to that URI.
83. How To...
Add a person to a collection.
GET /platform/collections/tree
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<collection>
<title>FamilySearch Family Tree</title>
...
<link rel=âpersonsâ href=â/path/to/persons/resourceâ/>
...
</collection>
</gedcomx>
84. How To...
Search a collection for persons.
â Read the collection.
â Find the link to the âperson-searchâ of the
collection.
â Fill in the parameters and issue the
request.
85. How To...
GET /platform/collections/tree
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<collection>
<title>FamilySearch Family Tree</title>
...
<link rel=âperson-searchâ
template=â/path/to/person/search{?q}â/>
...
</collection>
</gedcomx>
Search a collection for persons.
86. How To...
Do a âfullâ person read.
â Read the person.
â For each âembeddedâ link, get the
resource and embed it.
â Source references
â Discussion references
â Notes
â Relationships
87. How To...
Do a âfullâ person read.
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<person id=âP2â>
<name>...</name>
...
<link rel=âsource-referencesâ href=â/path/to/refsâ/>
<link rel=ânotesâ href=â/path/to/notesâ/>
<link rel=âchild-relationshipsâ href=â/path/to/relsâ/>
<link rel=âparent-relationshipsâ href=â/path/to/relsâ/>
<link rel=âspouse-relationshipsâ href=â/path/to/relsâ/>
...
</person>
</gedcomx>
88. How To...
Upload an artifact to a collection.
â Read the collection.
â Find the link to the âartifactsâ.
â POST the artifact.
89. How To...
Upload an artifact to a collection.
GET /platform/collections/tree
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<collection>
<title>FamilySearch Family Tree</title>
...
<link rel=âartifactsâ href=â/path/to/artifacts/resourceâ/>
...
</collection>
</gedcomx>
90. How To...
Edit the birth date of a person.
â Read the person.
â Find the link to the âconclusionsâ of the
person.
â POST the changes.
91. How To...
Edit the birth date of a person.
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<person id=âP2â>
<name>...</name>
...
<link rel=âconclusionsâ href=â/path/to/conclusionsâ/>
...
</person>
</gedcomx>
92. How To...
Read the list of photos on a person.
â Read the person.
â Find the link to the âartifactsâ of the
person.
93. How To...
Read the list of photos on a person.
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<person id=âP2â>
<name>...</name>
...
<link rel=âartifactsâ href=â/path/to/artifactsâ/>
...
</person>
</gedcomx>
94. How To...
Delete a person.
â Read the person.
â Find the âselfâ link.
â Apply the DELETE.
95. How To...
Delete a person.
<gedcomx xmlns=âhttp://gedcomx.org/v1â>
<person id=âP2â>
<name>...</name>
...
<link rel=âpersonâ href=â/path/to/selfâ/>
...
</person>
</gedcomx>