APIs 101: What are they? What do they have to do with genealogy?

No notes for slide

This session idea came out of RootsTech 2014, where I attended Innovators Day and the Developers Track for most of the conference. So many sessions were devoted to the topic of APIs, and these sessions were appropriately identified in the course descriptions with developers as the intended audience and with a ranking of intermediate to advanced technical knowledge. Yet these classes were pretty packed with non-developers who either thought they had more advanced technical skills than they really did (don’t we all?!), or who were simply curious and eager to learn. Sitting in the audience, I kept hearing people asking “What’s an API?”, yet not a single API session explained this. Consequently, I saw people grow frustrated and walk out mid session.

So this session is a primer, an introduction to the concepts of and uses for APIs, particularly in genealogy. For regular genealogists. It is a technical topic, so I do have to use some technical talk. But, I try to keep that to a minimum, and use analogies that should be understandable to the average genealogist.

My intent is for you to be able to gain a general understanding of and appreciation for APIs, and how they impact your genealogy work. And also to give the more adventurous of you some hands-on real life take away use cases that you can apply to your day to day genealogy research, writing, and organization.

First off, I need to point out that I am not a computer programmer. I am a web developer, and a very techie librarian. To many of you, the terms computer programmer and web developer may sound synonymous… but to those who work in my world, there is a big difference. The people at this conference who are teaching the other API sessions ARE programmers. They do much more heavy lifting than I do, including building APIs. I build the web applications that USE and play with APIs. The fun stuff.

So if you are a programmer, particularly a programmer who writes APIs, you are still welcome here. But please don’t ask me any questions about building or modifying APIs; for that I have to refer you to the other API sessions here. However, perhaps you’ll learn how to better “talk APIs” to the average person.

For those who are attending in hopes of learning how to build APIs, I do have some Next Steps resources listed on my syllabus at the end of this slideshow. However, I strongly urge you to attend (this year or next) the more advanced API sessions offered here at RootsTech.

And for those who simply want to learn more, or do some more in-depth hands-on learning and playing, I encourage you to state such on the feedback surveys that RoostTech will send out after the conference, or that’s currently loaded into their mobile app. And to email me with those suggestions. Because that will let us know your interests for future RootsTech workshops and presentations.

My syllabus will get updated after this conference, to include the various links and use cases demonstrated in this session. It has already been updated mid-conference, so if you downloaded or printed it prior to arriving here, I suggest doing so again.

Over the next month, I will also post a series of short video screencast tutorials on my website demonstrating the tools and uses cases presented.

For those of you who want to try out some of the Facebook Group use cases, but don’t want to “clutter up” your real Facebook Groups, I have set up a practice Sandbox group that will remain up through the end of March. Don’t annoy your genealogy society, surname group, or interest group by practicing these things out on a real Facebook Group used by others. That’s what the Sandbox is for. Simply request to join it, I will approve you, and I will bump you up to an Administrator since some of the examples require you to be a Group admin.

And finally, I list a REAL Facebook Group, “APIs for Genealogy”. This is a brand new PERMANENT Facebook Group where anyone can post questions, share examples, suggest tips, etcetera.

Even if you don’t know what an API is, or what specifically it does, chances are you already use APIs almost daily. If you have a smart phone, you use APIs. If you use Facebook, you use APIs. If you sync your genealogy database to something like Ancestry.com or FamilySearch, you use APIs.

Now for the big question… what exactly is an API?

For those who are more visual learners, a very basic diagram of how web APIs work. Yes, there are some non-web APIs, but since web APIs are what most people use (especially those of us doing genealogy), that is our focus in this session.

I promised to use as little technical jargon as possible, but I do have to introduce a few terms that you are likely to hear often in conversations or presentations about APIs. You can find a ton of information online if you care to go into depth more about any of these terms.

Web Service and APIs are often used interchangeably, which is not necessarily accurate. But for our purposes, please excuse me if you do hear me refer to once of these API examples as a web service. Same with mashups. Mashups have a much broader meaning, but in terms of web mashups, we couldn’t have those if it weren’t for APIs.

The only reason I draw our attention to CRUD, is for those who want to dabble further in learning how to build or work in a more technical capacity with APIs. Also to help all of you understand why not all apps or APIs provide the same type of functionality. Some APIs may only allow their data to be retrieved and viewed (for example, like “read only” files). While others may also allow their data to be modified, such as adding new records, editing a record, or deleting a record. Think about some of the FamilySearch mobile or desktop apps you might already use, and how some only allow you to retrieve and view records (instead of adding or modifying a record).

Every discussion here at RootsTech about APIs will most definitely include terms like SOAP and XML, and/or REST and JSON. So I just want you to have a basic understanding of their role in APIs. These are not programming languages. These are more like GEDCOM; formats for HOW data is packaged and exchanged between systems. Your GEDCOM files contain your genealogy data. GEDCOM also comes in different formats. When I export a GEDCOM from my Family Tree Maker database, it is formatted a bit differently than how something like RootsMagic or TNG formats and uses GEDCOM. SOAP+XML and REST+JSON are different standards for containing and exchanging data. These different types of containers do not talk to each other. Therefore each system has to decide on which type of container and exchange method it wants to use.

So WHY are APIs so popular, and why are APIs discussed so much here at RoostTech?

APIs break down data silos. If you recall from the slide defining APIs, I mention that they allow different systems to open up their data, expose it to each other, and exchange that data. Think about how FamilySearch records are now findable when using Ancestry.com.

APIs also allow for “real time” dynamic interoperability. Real time exchanging of data, and reach time sharing of functionality. When using two different systems that talk to each other via APIs, the lag time between these two systems is usually pretty brief (if noticeable at all). HOWEVER, note the asterisk next to “real-time.” Real-time does not always mean instantaneous. Some API providers (the system that is opening up an sharing its data with another system) place limits on how much or how often its data can be used. It requires a lot of resources (servers, bandwidth, staffing, technical expertise, etc.) to make APIs available. So some providers only allow their API to be used (“called”) every so many minutes, or only allow a certain number of calls(i.e., records to be requested or updated) over a set period of time. If you are a Twitter user and remember when Twitter used to experience a lot of Fail Whales, that was due to their APIs getting overwhelmed.

Coinciding with the concept of real-time interoperability, is what appears (at least to us end users) to be a much more easy exchange of data with using APIs. I put the term easy in quotes, because as any API provider (such as FamilySearch, Ancestry, or Facebook) can tell you… building out a scalable and sustainable API model for heavy use is not easy. As mentioned in the previous point, making APIs available requires a lot of resources. But to we normal people, APIs make things EASY to share and to sync data. Prior to things like APIs and data harvesting protocols such as the Open Archives Initiative (a subject for another session!) data had to be exchanged by exporting and importing a database. A big pain. To use an analogy with which most of you are familiar, think about exporting and importing your GEDCOM files. Yes, we still all have to do that sometimes. It’s never pretty, and it often leads to corrupted, missing, or mismatched data. Now think about how you sync your Family Tree Maker with your Ancestry Member Tree, or your RootsMagic with your FamilySearch FamilyTree. Isn’t that a lot less painful?

Another major plus for APIs is that there are now a lot fewer wheels that need reinventing. APIs allow third parties to use the same data (instead of collecting their own silos of data), and to share similar features and functionality. Instead building new apps on top of exiting apps, which extend or enhance functionality instead of competing against each other. Think about the suite of Partner Products that work with FamilySearch. Through FamilySearch’s Partnership program, other apps can simply build out cool new tools that work ON TOP of FamilySearch. A big win for us!

APIs have opened up a world of super cool super fun multimedia mashups, a few examples of which we will demonstrate here. And we could never have the variety of mobile apps (for smartphones and tables) that we do if if weren’t for APIs.

Do any of these logos look familiar to you? How often do you use these services? Guess what, these all either provide or use APIs that you employ daily.

Can you guess which is the most popular API?

According to Programmable Web, at the end of 2014, the most popular APIs of all time were 1) Facebook, 2) Google Maps, and 3) Twitter.

How about these logos? At least some of these should look very familiar to genealogists, and refer to products you probably use daily.

Examples previously mentioned already in this presentation include syncing Family Tree Maker with your Ancestry Member Tree, or syncing RootsMagic with FamilySearch’s FamilyTree.

These APIs do NOT all work together, and some are much more “open” with exposing and providing access to their APIs than others are.

I have to stress the points of caution that need to be taken when working with APIs. We are now (even unknowingly) extremely dependent upon APIs to carry out daily activities. Yet one cannot ever actually DEPEND on APIs.

Why?

APIs can change at any time. The API provider might go under, might decide to change its terms of use, might decide to start charging for its API, or might simply change its API code. When this happens, it can break your website, block your access to data or functionality, and break your workflow.

Months ago, when RootsTech first put out the call for proposals for this 2015 conference, my proposal specified two particular tools to teach, demonstrate, and visualize the concept of APIs: Yahoo Pipes and Google Code Playground. Yahoo and Google are major companies, not some rinky dink start-up in a basement. Yet when it came time for RootsTech to require a syllabus from presenters last November, pretty much all of the API examples I used to depend on in Yahoo Pipes no longer worked, and Google had simply done away with (without any explanation) its Code Playground. I was left high and dry, and panicked. I had to quickly come up with a Plan B, which thankfully still works as of today and is still free as of today.

This scenario doesn’t just happen to free API tools. It can happen when you pay for API access as well. Libraries often face this dilemma. At my job at a university library, I am facing this exact situation with one of our key vendors (Springshare) and two of its products we heavily use: LibGuides and LibAnswers. I will show the LibAnswers example in the demo part of this session. But my library is in the midst of upgrading to the newest version of both products. For two years, since redesigning our library website, our website has made heavy use of these APIs (particularly LibAnswers) throughout the pages of our website that are published through our XML-based content management system. Almost every single page on our library website “calls” and displays LibAnswers API code. Yet when the vendor released this latest (major) version upgrade, they changed how their API interacts with XSL. When I upgrade our LibAnswers product this spring, their API will literally break every single page on our library website that calls their API. Neither I nor my content management system vendor can make the two work together; we have to do this via a very ugly clunky “hack” (iFrames, for those who are web developers… nails on the chalkboard!). So my big task this next month is to work with (read that as “beg and plead”) my LibAnswers vendor to rewrite their API code to play nicely with our content management system. If this were a free API provider, I wouldn’t stand much chance of making that happen. But we pay for their product and their support (plus, Springshare provides phenomenal development support), so I am expecting (read that as “hoping”) they will make every attempt to help us out.

Treat what you do with APIs exactly how you SHOULD treat your own research notes and data (I said should, not what you actually do in practice). NEVER EVER EVER rely upon just one source. We are taught to seek multiple sources to corroborate facts. We SHOULD all backup our saved research files, and back them up to multiple places (there’s sessions here on that!). And you should never build out a website, blog, or workflow that depends solely on an API.

With all of this being said, I have to also stress that you should NEVER rely on a single one of the solutions demonstrated in my use cases to function as your real or SOLE backup. Remember… no SOLE backups. Multiple backups. Each of these use cases we discuss or try out should function as just one of many tools in your genealogy toolbox.

So…. Now that I’ve scared you into being cautious about depending upon APIs, you might be asking if APIs are even worth the risk?

Unless you want to continue using genealogy web services and apps like we used to have to do in the past (logging into a bunch of different sites to view or save records, manually retyping all of our data between services and apps, constantly exporting/importing/cleaning up GEDCOM)….. The answer is YES.

Do you use Facebook? Do you use a free blog tool? Do you use a free email service like Gmail or Yahoo? Do you save your research to free cloud storage apps like Google Drive, Dropbox, or Evernote? Do you save your precious photos on free photo storage and sharing sites like Facebook, Flickr, Picasa, and Instagram? Then you’re already taking the same risk you take when depending upon APIs. And you’re also reaping the same benefits. But hopefully, you do not depend solely on any single one of these services to store, organize, share, and publish your research.

Remember… no responsible genealogist justifies a single source as sufficient evidence to support a fact. Therefore, no responsible genealogist should depend upon a single API, web service, or tool to support your research and work!

Now, enough with the heavy learning. Let’s have some fun!

This is a very basic example of APIs in use, and one that many of you probably already employ on your websites and blogs. Or at least use everyday when visiting other sites on the web. The example on the left points to the social sharing buttons that display on every single post in my family history blog (actually, every single one of my blogs). Each of those buttons “calls” and works with the API for each respective web service: Facebook, Twitter, etc.

I will elaborate on this more explaining how it works with Facebook. On the blog post on the right, note the Facebook button surrounded in a purple box. The blue number displayed next to that button displays the number of times (at the time of this screenshot) that this particular blog post has been shared by someone (anyone) on Facebook --- whether on a personal Profile, on a brand organization Page, or in a Facebook Group. That number will increase each additional time the post is shared on Facebook. The button I have integrated into my Wordpress blog “calls” on Facebook’s API to query and display the number of shares on Facebook. Note that this API tells us ONLY the number of shares; it does not tell us WHO shared the post.

When one clicks on that Facebook button to share my post (the left example), you see the example on the right. This is what the post looks like when shared on Facebook. Some of you probably do this daily, many times a day. When that button is used to share the post, it is again “calling” on Facebook’s API, this time to write to Facebook in a manner that allows that share to get recorded in the count displayed next to the social sharing button on my blog post.

You have all probably done this at some time, whether sharing a blog post, news article, web page, etc. But, think back to the types of links you have shared on Facebook, and how sometimes no nice visual image or thumbnail (or even the wrong thumbnail) shows up when you post a link. Or how sometimes the wrong title or the wrong snippet (description) show up when you share a link. But in my example, the specific image I want from the post, as well as my hand-crafted title and post snippet, all correctly show up when I share the post. That is because these social sharing buttons (as well as a good quality optimized Wordpress theme) work specifically with Facebook’s Graph API (they have many different types of APIs), and the Graph API is what feeds the specific tags on Facebook’s end that populate the featured image, title, and description.

Now keep in mind that each one of those social sharing buttons calls a different API, each time a post is shared on each respective web service. Each “call” is talking to a different server, across a different distance. Each call to a different server slows down the load time on my blog. That is true of ANY type of API service implemented on a website. This is one of many tradeoffs necessary when using an API. The more API-dependent “bells and whistles” you put on your website or blog, the slower your blog will load. Sometimes frustrating and driving away traffic. But that is a topic for another presentation.

Here is another example with which you are probably already very familiar (and may be using on your own sites), but probably didn’t realize utilizes an API. This is a very basic embedded custom Google Map that I have added to one of my family history blog posts to illustrate some of the places associated with that blog post.

I LOVE LOVE LOVE Google Maps. I am a big time map nerd, and can spend HOURS working on maps – exploring maps for places my ancestors are associated with, as well as building and updating my own custom Google Maps to illustrate the same. And I use these heavily in my family history blog, because as you already know, maps are an excellent tool for genealogy. For a single ancestor or family, I often plot out various places associated with their lives: place of birth, place of death, place of marriage, residences, place of work, etc. This is particularly helpful to illustrate a migration pattern, say for example, to illustrate how one of my ancestral families emigrated from Missouri, across the plains, over the high Sierras, and then across the Central Valley, all in a single generation.

If you click on the “Custom Google Map” link, you can see the original native map on Google Maps, where I input the data. If you click on the link to my blog post, you can see that custom map within my blog post. From either spot, if you click on those red markers, a piece of descriptive information (and oftentimes, a relevant image) will be displayed about my family history. On the Google Maps end of that map, anytime I add, edit, or delete a new marker, the change is automatically displayed on the version of that same map that is included in my blog post.

Adding this map is done through a process called embedding. You may already have experience with embedding Google Maps, YouTube videos, Flickr albums, Facebook photos, Tweets, Instagram photos, etc. Embedding allows you to easily (with no coding experience) copy and paste a block of code into a web page or blog post to display the desired item. If that source map, video, photo, etcetera is completely deleted (off YouTube, Facebook, etc.) the version on your web page or blog post will also disappear. The data that is exchanged between the two systems (the map and map points, the video, the photo, etc.) is exchanged via an API provided by that source organization.

Playing with custom Google Maps and its APIs is one of the topics I would love to teach here in a hand-on workshop. So if this is an interest of yours, please note this in the feedback survey sent out after the conference or available now for each session in the mobile app. And send me an email request!

Do you happen to use (or have you seen) Darren Lythgoe’s TNG (The Next Generation of Genealogy Sitebuilding) product? The link on this slide will take you to Darren’s demo site, and he is doing in-person demos in the Exhibit Hall. It is an excellent product, which I have used off and on for years.

One of the coolest features of TNG is its use of the Google Maps API. Like the previous example from my blog, TNG displays custom Google Maps throughout the entire website. Each ancestor gets a dedicated web page. And anytime a location is specified for an event (birth, death, marriage, residence, etc.) that location is added to that ancestor’s map. The screenshot above shows you a few basic events for a single ancestor. Like my blog post example, each event is displayed through a numbered marker. Follow the hyperlink to view this on Darren’s demo TNG website.

Unlike my blog post example, however, this data is not entered from the actual (native) Google Maps interface. The data is entered from within TNG, and then updates things on the Google Maps end. My blog post example simply “reads” (from our earlier CRUD explanation) from the Google Maps API. TNG writes to and modifies the data exchanged with the Google Maps API (the “create”, “update”, and “delete” part of CRUD).

This is a screenshot of a YouTube video embedded into one of my family history blog posts. As just discussed, this is done through that easy copy and paste code, but also through YouTube’s API.

My maternal grandfather was orphaned as an infant and again as a toddler, separated from his older brothers, led a hard life with a foster family who never wanted to adopt him, and spent his adult life knowing nothing about his family or family history. He is the reason I became a genealogist. But unfortunately, not until after he died. So he never got to learn what I have discovered about his ancestors.

This is a blog post about the Buffalo, New York orphanage he and his brothers were placed in after their father died, and were still living in during the 1930 US Census and then when their mom died. The orphanage has been long closed (much of it burned), and is rumored to be slated for demolition. My family and I will NEVER get to walk inside this place, and may not ever get to see it even just from the outside. I am obsessive about finding and collecting photos and memories others have posted about the orphanage.

So you can imagine my joy when I stumbled across these video walk-throughs of the orphanage that someone else posted on YouTube! Which I of course, have to include on my family history blog to share with my family and with anyone else with ancestors from that orphanage. Like the Google Maps embed example, I am able to “read” the video data (including the built-in video player) via the Google Maps API.

But like any third party web service with content provided by and published by someone other than me, I have no control over that data. If YouTube goes under, or if the person who published it to YouTube decides to delete the video, make it private, or turn off the feature that allows others to embed the video, I am lost. I lose this extremely valuable genealogical record. I lose my ability to vicariously walk where my grandfather crawled and learned how to walk. That is the risk and tradeoff for depending upon a a web service and an API.

Unless, of course, I violate someone else’s intellectual property rights (don’t tell Judy Russell!), and use a hack app that allows me to download and archive for safekeeping (I did not say PUBLISH or SHARE) a YouTube video. I am not advocating for or endorsing that course of action. Just pointing out our own helplessness when depending upon APIs. Remember.. I said NEVER depend solely upon an API for your data or workflow.

Just like the YouTube example, this is a photo slideshow that I have embedded into my family history blog, showing photos I found on Flickr of my grandfather’s orphanage. The slideshow player and the data (the photos and attributed metadata) are made available through the Flickr API.

And just like the YouTube scenario, I lose these valuable records if Flickr goes out of business or if the photo owner takes down their account, deletes the photos, makes the photos private, or turns off the feature that allows others to embed the photos. Unlike YouTube, though, photo contributors can opt to allow others to legally download each individual image, and even to legally re-use (publish and share) those images by putting those images into the public domain or assigning a Creative Commons license (I am on Judy Russell’s good side again). If you look at the title slide for this presentation, I have assigned a Creative Commons license to this presentation (as well as my syllabus). I also assign a Creative Commons license to all of my photos that I upload to Flickr.

You can also choose to break the law and force-download images that Flickr account owners do not permit as allow downloads with re-usable licenses. But then you have to content with Judy Russell.

This example is that big horrible nightmare I mentioned earlier that I get to deal with at my work for a good month (and most likely, much longer). This is how I take advantage of the LibAnswers API by integrating it into almost every page on my academic library’s website.

LibAnswers is a web service that allows patrons to submit questions or comments to our library via a dedicated email address, or through an embedded question form. A team made up of librarians and staff from every operational area of the library receive those questions. Each incoming record generates a ticket that allows us to track the issue and the conversation associated with that issue (a paper trail, accountability, and issue statistics). The person in whose area of responsibility the question or comment falls responds to the question or comment.

The system also functions as a searchable knowledge base of Frequently Asked Questions. Our librarians and staff build out FAQs for questions they regularly get at the service desks (research help, circulation questions, etc.) as well as in research instruction sessions. When we see incoming questions or comments happening over and over again, we build out an FAQ for this. Every single public FAQ is categorized under one or more categories (topics), much like blog posts. Google Analytics is integrated in our LibAnswers, allowing us to see which FAQs receive the most visits (hits or traffic). Using the LibAnswers API, I am able to feed these categorized lists of FAQs (ranked in order of popularity via Google Analytics) into every relevant page on our main website. The screenshots above illustrate this. The screenshot on the left is of our live LibAnswers web service (the native interface) for all FAQs pertaining to the category of “Borrowing” (i.e., checking out books, course reserves, interlibrary loan, late fees, etc.). The screenshot on the right shows the top 10 “Borrowing” questions displayed in a bullet list on one of our web pages under the “Related Questions” heading. Just looking at that web page, one might think that someone had manually typed and built that bullet list, as well as the hyperlinks that lead back to the corresponding answer on our native LibAnswers interface. Updating that list as the 10 top questions change over time. But that would be a LOT of work, a HUGE amount of work. It’s how we used to have to do things BEFORE the days of APIs and reusable content. The API system allows me to dynamically “call” that list of top Related Questions, pretty it up in a list, store a single line of code in one spot in our content management system, and then push that list out (updated anytime a rank or a link changes) across ALL related web pages in a task that takes about 5 minutes to set up. That is the beauty of working with APIs!

Of course, as I explained under the Caution discussion, once I upgrade our LibAnswers system to their newest version, this will break on every single one of our library web pages that uses the API code. That is almost ALL of our library web pages. Unless and until the API provider (our LibAnswers vendor) is willing to modify their API code to play nicely with our XSL-based content management system.

By the way, every sizable genealogy archive or library should be using LibAnswers. It is an excellent high quality product, at an amazingly reasonable price, and comes with phenomenal customer and technical support.

We have already talked about FamilySearch’s API program quite a bit by this point. I simply want to exemplify the types of third party apps (approved Partners) that work on top of the FamilySearch API. This is only a sampling; visit that web page to see the ever-expanding list of web-based, desktop, and mobile products.

If you are already experiencing a bit of information overload by this point, I will just quickly refer to RootsMagic as an example. If you use the desktop or mobile version of RootsMagic to view and update records on the Family Tree, you are using the FamilySearch API. When you view their list of partner products, pay attention to the icons that note what type of functionality each individual app provides for interaction with Family Tree. Some just view data (Read), while others allow you to add (Create), Edit (Update), or Delete records – different levels of CRUD interaction.

And one final example of yes, another Google Maps API – just because it is my very favorite API, and one of my very favorite mashups – Historypin.

Historypin is a crowd-sourced (public user-contributed) digital archive. Individual users, as well as museums, archives, and libraries contribute content by “pinning” it to a specific location and time. The “location” part utilizes the Google Maps API. The timeline mashup allows you to view all pinned items in a specific location, over different spans of time. Content can be added or viewed through a web browser, or via mobile apps.

This particular mapped location displays digital objects that have been pinned in and around the area of Brooklyn, New York. Clicking on any object will display information about that object, as well as a larger view of that object. Use the Google Maps controls on the top left to zoom in and out of a location.

Like the TNG example, items are added to, edited on, or deleted from custom Google Maps through the Historypin interface; not through the actual Google Maps interface (like what you saw on my blog post example).

Following are just a handful of sample use cases that can be employed in your daily genealogical work.

To learn about additional use cases, be sure to follow my professional blog at www.colleengreene.com. Our new “APIs for Genealogy” Facebook Group is also a great place to learn about new uses cases, as well as to share some of your own! Starting in March, I will start posting regular short single use case video screencasts as well.

The tool that we are using to demonstrate the concept of APIs, and with which to provide you some real-life takeaway use cases for your own work, is IFTTT, which is an acronym for If This, Then That. Pronounced like “gift” without the “g”. IFTT is a (currently free) web service that is completely run off of APIs. It will allow you to visualize how APIs are called, retrieved, and displayed, without having to try to understand the actual API codes or know any programming.

You must create a free IFTTT account, and be logged in to it, in order to view the various features and functionality discussed here.

IFTTT was launched in 2011, and I use it daily in my research notes and notes organization.

If you’re wanting to get your hands dirty learning and playing with API programming, check out the resources to learn more that I post at the end of these slides.

IFTTT hinges together conditional statements that are called Recipes. This diagram from the IFTTT help documentation helps to visualize and dissect how Recipes work. If Condition #1 (the “this” or Trigger) happens, then it executes something (the “that” or Action).

The building blocks of Recipes are what are called Channels. These icons are a sampling of the 160+ channels currently available on IFTTT, and should look somewhat familiar to you. Each Channel is a specific web service (Gmail, Evernote, Facebook, etc.) that makes its API available through IFTTT.

These Channels are what are know in API jargon as API Providers or API Consumers. Some of these web services (like Facebook) allow Recipe “cooks” to both read and write to its API (remember that CRUD explanation from earlier?). While other web services (like Evernote) only allow one-way communication with its API. Evernote only allows Recipe cooks to write to its API (create Actions within Evernote); it does not allow Recipes to read from its API (take data out of Evernote, and use it another web service).

Use the link provided to access the Channels library on IFTTT, and see all of the different web services available for use. More get added each week.

IFTTT Channels include a variety of mobile web services too.

When you select a Channel, IFTTT will require you to Activate that Channel. After clicking on the Activate button, you will be prompted to log in to your own account on that particular web service (if an account is required, such as for email or Facebook) and authenticate your Channel. Some Channels, such as RSS Feeds, do not require authentication.

To quit using a particular Channel, just Deactivate it.

Once your have activated a Channel, you can start using it in Recipes. Since this example uses both Instagram and Dropbox, IFTTT will want you to activate both of those Channels.

Recipes are stored in Recipe libraries. When logged in, you will see a “Browse” link in the top navigation menu, which will allow you to review and select from public Recipes that other IFTTT cooks have created and chosen to share. The “Browse Recipes” link on this slide takes you to that library.

Every Recipe you add (whether active or not) gets stored in your personal Recipes library. This can be accessed from that same top navigation menu, using the “My Recipes” link.

Recipes can be created on the website, as well as using the mobile apps.

The easiest way to get the hang of using IFTT, and in particular how different Recipes behave, is to start by simply using public Recipes shared by others.

When you follow that “Browse” link on the main menu to access the public Recipes library, you will see a variety of access points for finding public Recipes.

The Search box at the very top will allow you to search for Recipes by Channel name. Try typing in the name of one of the Channels you already activated. In the example above, that would be Instagram. Instagram, as of this date, has almost 11,000 Recipes available! By default, Search results seem to display Recipes by rank – according to the number of times a Recipe has been marked as a favorite. The Search results show a visual icon for each Recipe, the web service logo associated with the IF part and also with the THEN part. In this case, our Recipe is using Instagram to do something to Dropbox. Next to each Recipe icon is the name of the Recipe, the name of the Recipe author, the number of times that Recipe has been added by other IFTTT users, and the number of times it has been marked as a favorite. While viewing the Search results, click on the Recipe icon to access that Recipe.

Going back to browsing that full public Recipe library, note the other access points for finding public Recipes.

Collections are Recipes that serve a particular purpose (type of mobile device, Road Trips, the Beach, etc.). I have asked IFTTT to add a Genealogy collection, or at least the ability to categorize Recipes so that other genealogists can easily find and share Recipes that are useful for doing genealogy.

IFTT features different types of Recipes on the public Recipe library home page. They also display the top Trending Recipes, as well as Recipes broken down into DO action items and IF conditional items.

If you hop back over to the main Channels menu and select a particular Channel, you’ll see that a selection of Popular recipes are displayed on each Channel page.

But what about if you want to create a brand new custom Recipe?

Clicking on that button will take you to the Recipe builder screen.
You will first be prompted for a THIS condition (the Channel from which you want something to happen). This will bring up that now familiar looking Channel menu, from where you need to select the desired THIS Channel.
Next the “Choose a Trigger” screen is displayed. Triggers are the number of different THIS conditions that a particular Channel’s API service allows IFTTT users to utilize. So the number of available Triggers varies from Channel to Channel. Review ALL available Triggers (including the descriptions) to identify the one you want for this particular Recipe.
Once you have selected a Trigger, you are prompted to Complete the Trigger Fields. Trigger Fields are a set of parameters available for that particular IF function. The Fields will display some common language help text. Once all desired Fields are completed, click on the Create Trigger button.
Now it’s time to populate the second part of your new Recipe – the THAT action. Like you did for Choosing a Trigger, select your desired THAT Channel for the Action, review the list of available Actions, and select the desired Action.
Just as you did with the Trigger Fields for the IF part of your new Recipe, fill out the Action Fields for your THAT Action. Default names, content, and paths are usually provided for each Action Field. You can keep the defaults, or if you are comfortable enough, modify them.
I almost always change the File name to something that makes sense when I come back across my personal Recipe in the My Recipes library.
I frequently change the target folder path if I am saving to Dropbox, Google Drive, or Evernote – usually a default folder if I want to go back in and clean it up (like applying Evernote Tags), or a default folder for this purpose (ex: IFTTT) in my Drive or Dropbox.
I RARELY change the actual content Field in an Action, so I highly recommend you leave this alone until you are much more familiar with the various web services parameters available in IFTTT Channels. This Action content Field is where you can see the different parameters associated with that Action’s API. IFTTT utilizes its own syntax however, instead of displaying the raw code.
Click the Create Action button when done. This will display a visual representation of your new Recipe. If it does not visually appear like it will carry out what you want to do, go back and modify it. Otherwise, select Create Recipe to finish designing your new personal Recipe.

Your new personal Recipe will not be displayed at the very top of your My Recipes library. Note how to the bottom right of each Recipe icon, IFTTT tells you when the Recipe was created, when it was last run, and how many times it has been run.

From this view, you can also:
Turn the Recipe off, or back on.
Check the Recipe, if you want to confirm it is correctly working. Although keep in mind that you the initial IF item has to get executed in order for the Recipe to run, and that some APIs might have a little bit of a lag time.
View the Recipe Logs to see each time a Recipe has fired or misfired.
Edit the Recipe if you want to make changes to it. I frequently go back in to apply a more helpful Title or Description.

Now finally… on to our first actual use case!

Since we are in the midst of two concurrent genealogy conferences here, we are starting off with a conference or event use case. When I organize an event (or even just attend an event), I like to follow the Twitter conversations (back channel) that reference that particular event. If you serve on your genealogy society’s conference, seminar, or programs committee, it can be extremely valuable to curate and archive those conversations to use as feedback for planning future events, doing outreach to existing and potential members, networking with other societies and genealogists, and to share with your board or marketing team.

So this use case follows the official hashtag for the FGS 2015 conference “#FGS2015”. Here we will search for and curate all public Tweets (from ANY Twitter user) that reference the #FGS2015 conference hashtag. We will then archive these in a cloud storage service, where we can also share that document with others in our society. Dropbox, Google Drive, and Evernote are some examples of cloud storage sites we can utilize on IFTTT.

If you want to play around with this Recipe yourself, select a Twitter hashtag along the lines of just “#genealogy” if you don’t have a specific one in mind.

I opted to go with Dropbox for this #FGS2015 example. If you click on the public link button, you can view the actual publicly shared file in my Dropbox account. But this screenshot will give you an idea of how this particular Recipe archives those Tweets to a single text file in my Dropbox account.

I set up this test Recipe on February 9th, shortly before the conference began, and I turned it off on February 12th, during the conference. Tweets are displayed with the oldest at the top, newest at the bottom. Each Tweet is separated by a series of dashes.

This screen should help you follow the particulars associated with this test Recipe. Refer back to slides 30 and 31 if you need a refresher on these screens.

At the top is my personal Recipe icon. Note the Twitter and Dropbox logos, as well as the description underneath.

Under the Recipe icon is the Trigger menu, where we are telling Twitter to DO something (IF) a search across Twitter discovers any new Tweet referencing the “#FGS2015” hashtag.

Note the Action menu on the right, and each Action Field.
I replaced the default Recipe title with one that makes more sense to me (for a file name in my Dropbox account).
I did not modify the default syntax in the content field.
I opted to go with the default file path to create a new Dropbox folder for purposes of teaching this session. But if I were doing this for my society, I would point the folder path to my real folder path (something like: FGS/Conferences/2015 Conference/Feedback).

I have included a link for you to view my now public Recipe, that I have shared with the entire IFTTT community in the public Recipes library.

Think about how handy it would be to be able to categorize “genealogy” Recipes. Then other genealogists and genealogical societies could quickly identify useful public Recipes that they could implement for themselves.

Another common use case that I employ daily in my genealogy work is this scenario – using IFTTT to create READABLE archived copies of my blog posts in one (or more) of my cloud storage services.

Why?

Although I run daily SQL backups of my self-hosted Wordpress blog databases, and generate a weekly XML post export of any Wordpress.com or Blogger-hosted blogs, those SQL and XML backups are not readable to the human eye. I can recover my data by exporting it into another blogging platform, but until it’s live in a new platform, those backups and exports don’t do me a lot of good. However, I cannot stress enough how critical it is to regularly backup your websites and blogs… but that is the topic for another class.

What might some of the reasons be for wanting a readable archive of every blog post?
Have you ever deleted a much-neglected stagnant blog, and then later changed your mind? I have! But having kept an archived readable copy of each prior post allowed me to cheat and recreate those posts with the original date and time stamps…. Because, yes, I had even deleted the old XML file of exported Blogger posts since I thought I was done with that blog.
Have you been wanting to delete an old stagnant much-neglected blog, but want to save copies of the posts for your research or reference files? I am in that same boat now, with a quilting blog for which I just don’t have the time or energy anymore to sustain. Yet, I spent a lot of time writing up tutorials and patterns in those posts, so I want to keep those in my patterns files in Evernote. I just don’t want the blog up anymore.
Do you put a lot of analysis and time in to your blog posts? I do! These should be a valuable part of your genealogy research notes! Clipping a readable copy of each family history blog post to my Evernote account allows me to incorporate those posts into my existing research system.
Sometimes when you do a blog export and then import it into another system (i.e., Blogger to Wordpress, or Wordpress.com to self-hosted Wordpress.org), the post formatting isn’t always totally clean. I like having these readable archived copies on hand to refer to when cleaning up post-migration.

If you want to take extra caution, create multiple Recipes to archive each blog post to a separate cloud storage system. I send mine to Evernote as well as Dropbox.

In this example, I am archiving readable copies of Blogger blog posts to my Evernote.

Each time IFTTT detects a new blog post published from my Blogger channel (only ONE Blogger blog can be tied to your Blogger channel) – the IF item – THEN a new Note is created in my Evernote account. I opt to send these to my default Evernote Notebook, instead of specific genealogy-focused Notebooks, because I like to do a little bit of post-Evernote import cleanup on each blog Note.

Note how the Recipe uses my blog post title as the title for the new Note. In the Recipe Actions fields, I tell the recipe to apply the “CJR” Tag, which is the Tag I use in Evernote for anything pertaining to my CJRoots (Colleen & Jeff’s Roots) family history blog. All hyperlinks on the blog post come through in the Evernote copy, as do all images. Oddly, this screenshot is a view of that new Note in my desktop Evernote Mac client, and you can see that the formatting is a little bit wonky in that preview wndow… extra spacing is added, and the images are all left-alighted instead of center-aligned. But if you click on the link to view my actual Evernote file in a web browser, you can see that the import came through nice and clean.

What sort of post-import cleanup do I do this new Note?
Add the appropriate surname, place, or topic Tags that I use in all of my genealogical Notes.
Add internal Note links when appropriate (I maintain a master research log Note for each ancestor or relation).
Create an internal Note link TO this new post Note, from the appropriate ancestor research log Notes (I’m so bad at remembering to LOG my research each day).
File the new blog Note under the appropriate Notebook. I only keep 2 Notebooks for ALL of my family history research: one Notebook for my side, one for my husband’s side.

Please heed my earlier warning at the start of this presentation about NEVER EVER EVER making these workflow solution use cases your ONLY backup source for data. These are just one of many tools you can and should be utilizing to archive and preserve your precious work.

This is a similar example, but from the REAL version of my family history blog – a self-hosted custom Wordpress blog. I only used a Blogger copy as a demo for this presentation.

While IFTTT does have a Wordpress Channel, like the Blogger Channel, only a single Wordpress blog can be attached to the Wordpress Channel. If you only have one Wordpress blog or website, no problem. But, if you’re a chronic over-blogger like me, you will be faced with the dilemma of having multiple Wordpress sites to connect to IFTTT.

The workaround?

Use the Feed Channel to accommodate additional Wordpress or Blogger blogs. Unlike the Wordpress or Blogger Channels, the Feed Channel can handle as many RSS feeds as you want. Instead of copying the RSS feed into the Channel settings, you do this at the Recipe level, adding a new Recipe for each RSS feed you want to use.

Click on my live Evernote file to view the archived blog post in Evernote in your web browser. Again, it’s not perfectly formatted, but it’s readable and useable. For some reason, my Wordpress Featured Image comes through twice… I am troubleshooting this issue. However I’d rather get that image twice that not have it displayed at all. Extra spacing is added between paragraphs, and the images were all left-aligned upon import into Evernote. Not a big deal. Still usable.

Facebook’s API Channel provides a wealth of use cases for genealogical work. I’ve noted some in this slide.

Since we’re already talking blog posts, we’ll stick with blog posts for this example too.

I am a member of (and administrator for) a lot of Facebook Groups. Too many! But, some are quite useful to my genealogy work. Like surname member groups. So I automatically cross-post my surname-related blog posts to the appropriate surname Facebook Group. While I find ALL of my surnames fascinating to read about, I know that my Gann relations are really only interested in my blog posts about the Gann family. Same with my Nieto side of the family. And my Flanagan side of the family.

Both Wordpress and Blogger allow you to generate topic-specific RSS feeds. In Wordpress, these are called Categories. In Blogger, they are Labels. I utilize the appropriate Channel (usually the RSS Feed Channel in my case, since I blog about ALL of my surnames) to send a copy of the appropriate surname posts to the respective surname Facebook Group.

If your society has a membership Facebook Group, or any special interest group Facebook Groups, this would also be a good use case for you.

These screenshots display two examples from two different Recipes. If you recall from my initial discussion introducing IFTTT, Recipes that might (when looking at the Recipe icon) appear to be identical can yield a slightly different Action (or result).

Each Recipe displays just the title and summary of the published blog post, with a link to the full post on the live blog. Yet the left example displays the full RSS feed link at the bottom of the summary. The Recipe output on the right generates a “Continue Reading” link that directs the reader to the full live blog post. And sadly, no images come through on the Facebook Group posts. But if you look at the example on the left, underneath of the RSS feed link, you can see the URL for my blog post’s Featured Image (a photo of a headstone for Walter Scott Gann). I am still working through various Facebook Group Recipes to try to identify one that will post the actual Featured Image, instead of just a link to that image.

Again, harkening back to the notion that Recipes which look similar can generate a slightly different Action… some Facebook Group Recipes require one to be a group administrator, while others simply allow one to be a member. Always read the Recipe description and Action content field closely, and always test. Don’t just assume a Recipe works the way you think it will. I frequently test out a few similar Recipes to find the one I want to keep.

If you were fortunate enough to attend my live presentation, this is the part where we walked through a use case demo on the big screen.

If you’re just now catching the archived version of my presentation, you will have to wait for me to publish my video screencast demos. But I do encourage you to try these demos out on your own.

Even those who attended the live presentation are encouraged to try these demos out on your own… we had too little time to really allow class attendees to play at IFTTT in class, and I had to quickly run us through the demonstrations.

Since this presentation was offered at the RootsTech conference, we had a real-time active RootsTech opportunity to use in this demo. This particular Recipe searched across Instagram for all public images that were tagged with the “#RootsTech” hashtag (the IF condition). It THEN automatically published any new such-tagged Instagram photos to the test Sandbox Facebook Group that I set up for this class.

Now, before you create this Recipe, you will need to activate your Instagram channel and join the class Sandbox Facebook Group.

Why the class Sandbox Facebook Group? So you can play around without cluttering up your REAL Facebook Groups. But if you prefer to play in those and clutter them up, then go for it. This Sandbox group will get deleted after March 31, 2015.

Another good use case for you to try out on your own is archiving all new posts from a Facebook Group to a cloud storage service like Evernote. Again, you are welcome to join and test this out in the class Sandbox Facebook Group if you want.

Why archive Facebook Group posts? Again, for use as research notes. Some of my surname Facebook Groups are pretty active, and share some valuable family history leads. I want to capture all of those in my Evernote research system, file them in the appropriate Notebook, and apply the appropriate Tags.

If your society or special interest group maintains a Facebook Group for members, you might want to archive these conversations in your favorite cloud storage service to preserve the institutional memory, and share that folder or note system with your fellow board members or interest group leaders.

We have touched on and discussed all of these points throughout this presentation. However, they all warrant another reminder.

This presentation was meant to convey the basic concepts of APIs, how they are used by many of your daily web service providers, and to give you a set of hands-on takeaway tools that you might be able to use in your own work.

But, this is just the tip of the iceberg!

There is so much potential for continued incremental learning experiences at upcoming conferences, or even as a hands-on workshop through your society or interest group.

If you want to see more of this topic, especially some hands-on workshops, at next year’s RootsTech or FGS conferences…. tell them! Conference attendees all received an email survey from RootsTech and/or FGS. Use that opportunity. The RootsTech mobile app has a Submit Feedback option built into each session. Find this session in your schedule on the mobile app and provide that feedback. If it’s too late to reply to those surveys, email RootsTech or FGS. Or hit them up on their Facebook or Twitter pages.

The NextGen Genealogy Network hosts educational Google Hangouts, which would be a great venue for sharing 1 or 2 quick next steps or use cases.

Join the new “APIs for Genealogy” Facebook Group to learn about upcoming learning opportunities.

And definitely feel free to email me with your feedback. Knowing your interests or specific questions will help me craft presentation and workshop ideas for future conferences, webinars, or video tutorials. I am happy to answer your questions or entertain your ideas. If I can’t provide you with a specific answer or resource, I will find someone who can.

You can also reach me via the new “APIs for Genealogy” Facebook Group!

But, most of all, it is important that you practice, try things out, and continue to learn!

Join the new permanent “APIs for Genealogy” Facebook Group. This is NOT the same thing as the class Sandbox Facebook Group. This permanent one is a virtual water cooler where anyone can post questions, share tips, showcase examples, etc.

Follow my professional blog for tips and tutorials.

And see the updated syllabus for suggestions on Lynda.com tutorials, as well as online courses and web tutorials.

Thank you for your time!

APIs 101: What are they? What do they have to do with genealogy?

Colleen Greene

APIs 101: What are they? What do they have to do with genealogy?