@@ -1,4 +1,4 @@ -== Google Contacts API +== Basic usage instructions Fetch users' contact lists from your web application without asking them to provide their passwords. @@ -6,39 +6,41 @@ provide their passwords. First, register[http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html] your application's domain. Then make users follow this URL: - Contacts::Gmail.authentication_url('http://mysite.com/invite') + Contacts::Google.authentication_url('http://mysite.com/invite') They will authenticate on Google and it will send them back to the URL provided. Google will add a token GET parameter to the query part of the URL. Use that token in the next step: - gmail = Contacts::Gmail.new('example@gmail.com', params[:token]) + gmail = Contacts::Google.new('example@gmail.com', params[:token]) contacts = gmail.contacts #-> [ ['Fitzgerald', 'fubar@gmail.com', 'fubar@example.com'], ['William Paginate', 'will.paginate@gmail.com'], ... ] -Read more in Contacts::Gmail. I plan to support more APIs (Microsoft, etc); -feel free to contribute. +Read more in Contacts::Google. I plan to support more APIs (Microsoft Live, for +starters); feel free to contribute. -Author: Mislav Marohnić (mislav.marohnic@gmail.com) +Author: <b>Mislav Marohnić</b> (mislav.marohnic@gmail.com) -== Specdoc +== Documentation auto-generated from specifications -Contacts::Gmail.authentication_url +Contacts::Google.authentication_url - generates a URL for target with default parameters - should handle boolean parameters - skips parameters that have nil value +- should be able to exchange one-time for session token -Contacts::Gmail -- should be set to query contacts from a specific account +Contacts::Google - fetches contacts feed via HTTP GET +- handles a normal response body - handles gzipped response - raises a FetchingError when something goes awry - parses the resulting feed into name/email pairs +- parses a complex feed into name/email pairs - makes modification time available after parsing -Contacts::Gmail GET query parameter handling +Contacts::Google GET query parameter handling - abstracts ugly parameters behind nicer ones - should have implicit :descending with :order - should have default :limit of 200 README.rdoc @@ -40,7 +40,7 @@ end desc 'Generate RDoc documentation' Rake::RDocTask.new(:rdoc) do |rdoc| rdoc.rdoc_files.add ['README.rdoc', 'MIT-LICENSE', 'lib/**/*.rb'] - rdoc.main = 'README.rdoc' # page to start on + rdoc.main = 'README.rdoc' rdoc.title = 'Google Contacts API' rdoc.rdoc_dir = 'doc' Rakefile @@ -10,6 +10,7 @@ require 'stringio' module Contacts # == Fetching Google Contacts + # # Web applications should use # AuthSub[http://code.google.com/apis/contacts/developers_guide_protocol.html#auth_sub] # proxy authentication to get an authentication token for a Google account. @@ -27,6 +28,22 @@ module Contacts # #-> [ ['Fitzgerald', 'fubar@gmail.com', 'fubar@example.com'], # ['William Paginate', 'will.paginate@gmail.com'], ... # ] + # + # == Storing a session token + # + # The basic token that you will get after the user has authenticated on Google is valid + # for only one request. However, you can specify that you want a session token which + # doesn't expire: + # + # Contacts::Google.authentication_url('http://mysite.com/invite', :session => true) + # + # When the user authenticates, he will be redirected back with a token which still isn't + # a session token, but can be exchanged for one! + # + # token = Contacts::Google.sesion_token(params[:token]) + # + # Now you have a permanent token. Store it with other user data so you can query the API + # on his behalf without him having to authenticate on Google each time. class Google DOMAIN = 'www.google.com' AuthSubPath = '/accounts/AuthSub' # all variants go over HTTPS @@ -89,7 +106,7 @@ module Contacts @base_path = "/m8/feeds/contacts/#{CGI.escape(@user)}/base" end - def get(params) + def get(params) #:nodoc: response = Net::HTTP.start(DOMAIN) do |google| google.get(@base_path + '?' + query_string(params), @headers) end lib/contacts/google.rb 714191ef18e397ef67d4cd1a1c3cc49f07e19828 Mislav Marohnić mislav.marohnic@gmail.com http://github.com/mislav/contacts/commit/0c7ee8db976f6f9240864ef32a7b6d9e64986bc0 0c7ee8db976f6f9240864ef32a7b6d9e64986bc0 2008-03-16T18:53:18-07:00 2008-03-16T18:53:18-07:00 doc update: README and of getting session tokens c7c75ab65953b5867f016b2f6cd75bc7f3e8fecf Mislav Marohnić mislav.marohnic@gmail.com