Fork me! YQL Open Tables!

You might have heard about the Yahoo! Query Language (YQL) by now. I know I've been banging on about it enough. As we say in Britain: it's the mutt's nuts. Get Web data but do it like calling a database. That's pretty sweet.

With YQL Open Tables you can contribute back to YQL by sharing your own tables for web services you like. Currently we have almost 100 community Open Tables. You can see them in the YQL console by clicking the "Show Community Tables" link.


Once you've done that you'll get a list of new and exciting tables to play with and as you can see there a lot of popular services to play with:

List of tables including amazon, bit.ly, dopplr, etsy, friendfeed, etc

That's how awesome community Open Tables are, and how much of a part of YQL we consider them to be. So let's get down to the nitty gritty, how do you get your awesome Open Table into that list? Right now we host all of our community Open Tables on Github. This means you can fork us make some updates and then make a "pull request".

Let's break that down. If you've never used Git or GitHub have no fear! Github have some handy guides such as Get Git on Mac or Using Git and GitHub for the Windows for newbies. Have a look at those to get started. You should also register on Github (it's free for Open Source projects).

Importantly don't forget to set up your SSH keys without this you won't be able to properly push or pull changes from your repositories.

Once you are all set to roll. Then you can fork us. This will give you your own version of yql-table on Github.

Once you have your own fork it will look something like this:

sh1mmer/yql-tables page. Edit, pull request, etc buttons available

The "Pull Request" button allows you to send back changes from your fork to the main YQL repository. Once you issue a Pull Request to the moderators of the main repo (repository), such as yours truly, they will get an email telling them someone wants to merge in some changes. We'll take a look at what you built and merge it in.

Of course, you won't have any changes when you first fork. So you'll want to download the code to your local machine and work on it from there. It's a pretty easy git command simply go to a directory where you want your project and then run a command like:


git clone git://github.com/sh1mmer/yql-tables.git


The git clone command is the same for everyone, but you'll need to copy your clone URL from your Github fork page (see the example above). You should now have a working Git repository on your local machine with all the YQL tables. Why don't you make a new directory in this repo and start hacking on your new YQL Open Data Table?

Once you finish your table to your satisfaction, you'll need to commit it to your local Git repo. You can do this by running this command in the root of your repo:


git add <directory>
git commit -m "Adding new awesome YQL Open Data Table for X service"

Replace the <directory> with the name of the directory you put your table files in. Also please use a meaningful a commit message as possible as it will help us review your submission when you send the files to us. For example when I added a Regular Expressions (regex) table for YQL I got this output:


enki:~/Code/yql-tables $ git add regex
enki:~/Code/yql-tables $ git commit -m "adding regex table to yql to filter text by JS regex"
Created commit fdd9ab1: adding regex table to yql to filter text by JS regex
1 files changed, 1 insertions(+), 0 deletions(-)
create mode 100644 regex/regex.xml
enki:~/Code/yql-tables $

Now that your code is committed to your local repo, you can push your changes back up to your Github repo. Whenever you clone a repo from Github, it helpfully leaves you a remote source called origin. In order to send the code back to Github, you can run the following command:


git push origin master

This pushes the Git branch called master back to the remote source called origin. Your forked repo on Github should now be up-to-date with the changes you made on your local machine. You can refresh the page in order to see your new changes. You are also now ready to make a pull request back to the main repo for yql-tables. So go ahead and hit the pull request button!

You'll need to type in a descriptive message for us, and then send the pull request to the yql account which hosts the YQL official repository.

You'll get a confirmation and you're done! We'll let you know when we add your table. I look forward to seeing many more YQL tables chocked full of amazing data.

Tom Hughes-Croucher (sh1mmer on Github)
Yahoo! Developer Network