Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

doc update: README and of getting session tokens

  • Loading branch information...
commit 0c7ee8db976f6f9240864ef32a7b6d9e64986bc0 1 parent 714191e
@mislav mislav authored
Showing with 32 additions and 13 deletions.
  1. +13 −11 README.rdoc
  2. +1 −1  Rakefile
  3. +18 −1 lib/contacts/google.rb
View
24 README.rdoc
@@ -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
View
2  Rakefile
@@ -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'
View
19 lib/contacts/google.rb
@@ -10,6 +10,7 @@
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 @@ def initialize(user_id, token)
@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
Please sign in to comment.
Something went wrong with that request. Please try again.