From 56c34bd5feab59fe322e83115ff3bdeb7a0d4365 Mon Sep 17 00:00:00 2001 From: Justin Weiss <justin@uberweiss.org> Date: Fri, 14 Jan 2011 10:24:24 -0800 Subject: [PATCH] First doc pass --- .gitignore | 1 + README.rdoc | 61 ++++++++++++++++++++++++++++ examples/avvo_cli.rb | 9 +++- lib/avvo_api.rb | 9 ++-- lib/avvo_api/address.rb | 24 ++++++----- lib/avvo_api/advanced_training.rb | 40 ++++++++++-------- lib/avvo_api/base.rb | 9 ++-- lib/avvo_api/doctor.rb | 17 ++++---- lib/avvo_api/headshot.rb | 14 ++----- lib/avvo_api/language.rb | 10 ++--- lib/avvo_api/lawyer.rb | 15 +++---- lib/avvo_api/phone.rb | 26 ++++++++---- lib/avvo_api/professional_methods.rb | 19 +++++---- lib/avvo_api/review.rb | 20 ++++----- lib/avvo_api/school.rb | 16 ++++---- lib/avvo_api/specialty.rb | 17 ++++---- lib/avvo_api/version.rb | 2 +- 17 files changed, 195 insertions(+), 114 deletions(-) create mode 100644 README.rdoc diff --git a/.gitignore b/.gitignore index 9f30a35..006851a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ pkg/* *.gem .bundle +doc/* \ No newline at end of file diff --git a/README.rdoc b/README.rdoc new file mode 100644 index 0000000..ac42446 --- /dev/null +++ b/README.rdoc @@ -0,0 +1,61 @@ += Avvo API Client + +This gem provides an +{ActiveResource}[http://api.rubyonrails.org/classes/ActiveResource/Base.html]-based +client to information on {Avvo}[http://www.avvo.com], a directory of lawyers and loctors. + +== Requirements + +Apart from the gems installed as dependencies, this gem requires an +account on Avvo associated with an API key. Visit the {API +Documentation}[http://api.avvo.com] for details. + +== Usage + +Somewhere during your app's initialization, you should include the gem +and set it up with your Avvo credentials: + + require 'avvo_api' + AvvoApi.setup('user@avvo.com', 'password') + +For the most part, the models supplied by this gem should act like +ActiveRecord models. These models parallel the resources listed on +http://api.avvo.com, and everything accessible from the Avvo API is +accessible using this gem. + +== Examples + +Details about the specific information returned by these calls can be +found in the documentation at http://api.avvo.com. + +=== Find a lawyer with a known ID + + l = AvvoApi::Lawyer.find(28995) + +=== Find a lawyer based on known attributes, like email, zip code, etc. + + l = AvvoApi::Lawyer.resolve(:name => 'Mark Britton', :zip_code => '98101') + +=== Search for lawyers matching a keyword in a specific location + + AvvoApi::Lawyer.search(:q => 'criminal defense', :loc => 'seattle') + +=== Retrieve the headshot URL for a lawyer + + AvvoApi::Lawyer.find(28995).headshot.headshot_url + +or + + AvvoApi::Headshot.find(:one, :params => {:lawyer_id => 28995}).headshot_url + +=== Getting a list of addresses for a doctor + + addresses = AvvoApi::Doctor.find(1).addresses + +or + + addresses = AvvoApi::Address.find(:all, :params => {:doctor_id => doctor.id}) + +=== Getting the main address for a doctor + + main_address = AvvoApi::Address.main(:doctor_id => doctor.id) \ No newline at end of file diff --git a/examples/avvo_cli.rb b/examples/avvo_cli.rb index f4b1fa5..c54ff1e 100644 --- a/examples/avvo_cli.rb +++ b/examples/avvo_cli.rb @@ -21,7 +21,14 @@ puts opts exit(1) else - config = YAML.load(File.read(File.expand_path("~/.avvo"))) + begin + config = YAML.load(File.read(File.expand_path("~/.avvo"))) + rescue + puts "Please put your Avvo API credentials in ~/.avvo. This is a simple yaml file, which should look like: +user: email@domain.com +password: your_avvo_password" + exit(1) + end AvvoApi.setup(config["user"], config["password"]) AvvoApi::Base.site = 'http://localhost.local:3000' diff --git a/lib/avvo_api.rb b/lib/avvo_api.rb index 429ac5f..3603834 100644 --- a/lib/avvo_api.rb +++ b/lib/avvo_api.rb @@ -1,7 +1,7 @@ require 'avvo_api/base' require 'avvo_api/professional_methods' -# The Avvo API Client. +# The Avvo API Client. All API models live in this module. module AvvoApi autoload :Lawyer, 'avvo_api/lawyer' @@ -15,9 +15,9 @@ module AvvoApi autoload :AdvancedTraining, 'avvo_api/advanced_training' autoload :Review, 'avvo_api/review' - # Sets up the credentials the ActiveResource objects will use to - # access the Avvo API. - def self.setup(user, password) + # Tells this client to use +email+ and +password+ to authenticate to + # the Avvo API. + def self.setup(email, password) AvvoApi::Base.password = password AvvoApi::Base.user = user end @@ -25,5 +25,4 @@ def self.setup(user, password) # Post parameters as <tt>{:lawyer => {...params...}}</tt> so the server # can separate the object's params from the request params - ActiveResource::Base.include_root_in_json = true diff --git a/lib/avvo_api/address.rb b/lib/avvo_api/address.rb index 38b63ae..b3baf0f 100644 --- a/lib/avvo_api/address.rb +++ b/lib/avvo_api/address.rb @@ -1,19 +1,19 @@ # Represents an address. One of the following attributes MUST # be set when using this model: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # This model has the following attributes: # -# * id -# * address_line1 -# * address_line2 -# * city -# * state -# * postal_code -# * latitude -# * longitude +# * id +# * address_line1 +# * address_line2 +# * city +# * state +# * postal_code +# * latitude +# * longitude # class AvvoApi::Address < AvvoApi::Base belongs_to :lawyer @@ -21,7 +21,9 @@ class AvvoApi::Address < AvvoApi::Base has_many :phones # Returns the 'main' address associated with the passed in - # professional. This is usually the one you want. + # professional. This is usually the address you want to + # use. +params+ is a hash of <tt>{:lawyer_id => lawyer.id}</tt> or + # <tt>{:doctor_id => doctor.id}</tt> def self.main(params) response = self.get(:main, params) if response && response["id"] diff --git a/lib/avvo_api/advanced_training.rb b/lib/avvo_api/advanced_training.rb index 3184c52..14799f1 100644 --- a/lib/avvo_api/advanced_training.rb +++ b/lib/avvo_api/advanced_training.rb @@ -1,27 +1,35 @@ +# Constants representing the possible values of the +# advanced_training_type_id parameter of AvvoApi::AdvancedTraining +module AvvoApi::AdvancedTrainingType + + # Unknown training type + UNKNOWN = 1 + + # Represents an internship + INTERNSHIP = 2 + + # Represents a residency + RESIDENCY = 3 + + # Represents a fellowship + FELLOWSHIP = 4 +end + # Represents advanced training, like residencies, for doctors. This # model is only applicable to doctors. The following attributes MUST # be set when using this model: # -# * doctor_id +# * doctor_id # # This model has the following attributes: # -# * id -# * advanced_training_type_id: an AdvancedTrainingType constant -# * specialty_name: The name of the specialty this advanced training is in -# * specialty_id: The ID of the specialty, if known -# * hospital_name: The normalized name of the hospital. This will be -# resolved by Avvo when it is set by this client. -# * hospital_id: The id of the hospital, if known. -# * graduation_date: The date this training was completed +# * id - The model's id +# * advanced_training_type_id - an AvvoApi::AdvancedTrainingType constant +# * specialty_name - The name of the specialty this advanced training is in +# * hospital_name - The normalized name of the hospital. This will be +# resolved by Avvo when it is set by this client. +# * graduation_date - The date this training was completed # -module AvvoApi::AdvancedTrainingType - UNKNOWN = 1 - INTERNSHIP = 2 - RESIDENCY = 3 - FELLOWSHIP = 4 -end - class AvvoApi::AdvancedTraining < AvvoApi::Base belongs_to :doctor end diff --git a/lib/avvo_api/base.rb b/lib/avvo_api/base.rb index 1d5dae6..765e95e 100644 --- a/lib/avvo_api/base.rb +++ b/lib/avvo_api/base.rb @@ -1,12 +1,13 @@ -# The class that all AvvoApi resources should inherit from. This -# class fixes and patches over a lot of the broken stuff in -# Active Resource, and the differences between the client-side Rails -# REST stuff and the server-side Rails REST stuff. require 'reactive_resource' + module AvvoApi + # The class that all AvvoApi resources inherit from. This sets up the + # base URL and URL structure that the rest of the models use to hit + # Avvo. class Base < ReactiveResource::Base + # The current version of the Avvo API API_VERSION = 1 self.site = "https://api.avvo.com/" diff --git a/lib/avvo_api/doctor.rb b/lib/avvo_api/doctor.rb index e110856..39159d4 100644 --- a/lib/avvo_api/doctor.rb +++ b/lib/avvo_api/doctor.rb @@ -1,13 +1,14 @@ # Represents a doctor on Avvo. Attributes include: # -# * id: The id of this doctor -# * firstname: the first name of this doctor -# * middlename: the middle name of this doctor -# * lastname: the last name of this doctor -# * suffix: the suffix of the doctor's name -# * email_address -# * website_url -# * profile_url +# * id: The id of this doctor +# * firstname: the first name of this doctor +# * middlename: the middle name of this doctor +# * lastname: the last name of this doctor +# * suffix: the suffix of the doctor's name +# * avvo_rating: The doctor's Avvo Rating, from 0.0 to 10.0 +# * email_address +# * website_url +# * profile_url # class AvvoApi::Doctor < AvvoApi::Base has_many :addresses diff --git a/lib/avvo_api/headshot.rb b/lib/avvo_api/headshot.rb index 9b889fe..f42316a 100644 --- a/lib/avvo_api/headshot.rb +++ b/lib/avvo_api/headshot.rb @@ -1,26 +1,20 @@ # Represents a professional's headshot. Each professional only has one # headshot, so finding a headshot should happen with the following call: # -# AvvoApi::Headshot.find(:one, :lawyer_id => l.id) +# AvvoApi::Headshot.find(:one, :lawyer_id => l.id) # # When using this model, one of the following attributes MUST be set: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # This model has the following attribute: # -# * headshot_url: The url to the standard-size headshot. -# -# When creating a headshot, you should set the Base64'd image data (in -# JPG or PNG format) to the write_only +headshot_data+ attribute. Avvo -# will do any compositing or cropping for you. +# * headshot_url: The url to the standard-size headshot. # class AvvoApi::Headshot < AvvoApi::Base - singleton belongs_to :lawyer belongs_to :doctor - end diff --git a/lib/avvo_api/language.rb b/lib/avvo_api/language.rb index 50edf95..33bcea2 100644 --- a/lib/avvo_api/language.rb +++ b/lib/avvo_api/language.rb @@ -1,14 +1,14 @@ # Represents a language. One of the following attributes MUST # be set when using this model: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # This model has the following attributes: # -# * id -# * name: The language name. -# * specialty_id: The language id. 'name' takes priority over this if both are set. +# * id +# * name: The language name. +# * specialty_id: The language id. 'name' takes priority over this if both are set. # class AvvoApi::Language < AvvoApi::Base belongs_to :lawyer diff --git a/lib/avvo_api/lawyer.rb b/lib/avvo_api/lawyer.rb index 995c7ce..dc2e8d1 100644 --- a/lib/avvo_api/lawyer.rb +++ b/lib/avvo_api/lawyer.rb @@ -1,14 +1,15 @@ # Represents a lawyer on Avvo. Attributes include: # -# * id: The id of this lawyer -# * firstname: the first name of this lawyer -# * middlename: the middle name of this lawyer -# * lastname: the last name of this lawyer -# * suffix: the suffix of the lawyer's name -# * email_address -# * website_url +# * id: The id of this lawyer +# * firstname: the first name of this lawyer +# * middlename: the middle name of this lawyer +# * lastname: the last name of this lawyer +# * suffix: the suffix of the lawyer's name +# * email_address +# * website_url # class AvvoApi::Lawyer < AvvoApi::Base + has_many :addresses has_many :reviews has_many :schools diff --git a/lib/avvo_api/phone.rb b/lib/avvo_api/phone.rb index 81ef825..234c520 100644 --- a/lib/avvo_api/phone.rb +++ b/lib/avvo_api/phone.rb @@ -1,28 +1,36 @@ -# Constants to be used for +phone_type_id+ in AvvoApi::Phone +# Constants representing the various values for +phone_type_id+ in AvvoApi::Phone module AvvoApi::PhoneType + + # There is no type specified for this number UNKNOWN = 1 + + # This is an office number OFFICE = 2 + + # This is a fax number FAX = 3 + + # This is a mobile number MOBILE = 4 end # Represents a phone number tied to an address. One of the # following attributes MUST be set when using this model: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # Additionally, the following attribute MUST be set when using this model: # -# * address_id +# * address_id # # This model has the following attributes: # -# * id -# * phone_number: The phone number. Will be normalized by Avvo. -# * phone_type_id: The type of the phone number, as an AvvoApi::PhoneType -# constant. (Only applicable when creating or updating records) -# * phone_type: A string representation of the phone type +# * id +# * phone_number: The phone number. Will be normalized by Avvo. +# * phone_type_id: The type of the phone number, as an AvvoApi::PhoneType +# constant. (Only applicable when creating or updating records) +# * phone_type: A string representation of the phone type # class AvvoApi::Phone < AvvoApi::Base belongs_to :address diff --git a/lib/avvo_api/professional_methods.rb b/lib/avvo_api/professional_methods.rb index 58fe384..ea305b8 100644 --- a/lib/avvo_api/professional_methods.rb +++ b/lib/avvo_api/professional_methods.rb @@ -1,12 +1,13 @@ -module AvvoApi::ProfessionalMethods +module AvvoApi::ProfessionalMethods # :nodoc: + # Methods that are shared between professionals. module ClassMethods # Search avvo for a list of the top 10 professionals matching the # passed-in parameters. Accepts the following parameters: # - # q: The search query - # loc: The location to search in + # [q] The search query + # [loc] The location to search in # # These parameters match the search boxes on the Avvo website. # @@ -27,12 +28,12 @@ def search(params) # Attempts to find a professional on Avvo that matches the # passed-in params. Currently accepts the following params: # - # name: The full name of the lawyer you are trying to find - # phone: The phone number of the lawyer, in the format XXX-XXX-XXXX - # fax: The fax number of the lawyer, in the format XXX-XXX-XXXX - # address: The full address of the lawyer - # zip_code: The zip code of the lawyer - # email_address: The e-mail address of the lawyer + # [name] The full name of the lawyer you are trying to find + # [phone] The phone number of the lawyer, in the format XXX-XXX-XXXX + # [fax] The fax number of the lawyer, in the format XXX-XXX-XXXX + # [address] The full address of the lawyer + # [zip_code] The zip code of the lawyer + # [email_address] The e-mail address of the lawyer def resolve(params) response = self.get(:resolve, :params => params) if response && response[collection_name] diff --git a/lib/avvo_api/review.rb b/lib/avvo_api/review.rb index 2b02853..00b5c57 100644 --- a/lib/avvo_api/review.rb +++ b/lib/avvo_api/review.rb @@ -1,19 +1,19 @@ # Represents a review for a professional. One of the following # attributes MUST be set when using this model: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # This model has the following attributes: # -# * id -# * overall_rating: The overall rating (out of 5 stars) given by this review. -# * title: The review's title -# * body: The first 150 characters of the review's body -# * url: A link to the review on Avvo -# * posted_by: The author of the review -# * posted_at: The date this review was posted -# * updated_at: The last time this review was updated +# * id +# * overall_rating: The overall rating (out of 5 stars) given by this review. +# * title: The review's title +# * body: The first 150 characters of the review's body +# * url: A link to the review on Avvo +# * posted_by: The author of the review +# * posted_at: The date this review was posted +# * updated_at: The last time this review was updated # class AvvoApi::Review < AvvoApi::Base belongs_to :lawyer diff --git a/lib/avvo_api/school.rb b/lib/avvo_api/school.rb index a53cb5c..35a1b77 100644 --- a/lib/avvo_api/school.rb +++ b/lib/avvo_api/school.rb @@ -1,18 +1,16 @@ # Represents a school attended by a professional. One of the following # attributes MUST be set when using this model: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # This model has the following attributes: # -# * id -# * name: The name of the school. When set, this will be resolved by Avvo. -# * degree_level_name: The level of degree awarded at this school. BA, BS, JD, etc. Will be resolved by Avvo. -# * degree_level_id: The id of the degree level, if known. -# * degree_area_name: Major or area of study. Will be resolved by Avvo. -# * degree_area_id: The id of the degree area, if known. -# * graduation_date: The date the professional graduated from this school. +# * id +# * name: The name of the school. When set, this will be resolved by Avvo. +# * degree_level_name: The level of degree awarded at this school. BA, BS, JD, etc. Will be resolved by Avvo. +# * degree_area_name: Major or area of study. Will be resolved by Avvo. +# * graduation_date: The date the professional graduated from this school. # class AvvoApi::School < AvvoApi::Base belongs_to :lawyer diff --git a/lib/avvo_api/specialty.rb b/lib/avvo_api/specialty.rb index 9480078..32e1a1f 100644 --- a/lib/avvo_api/specialty.rb +++ b/lib/avvo_api/specialty.rb @@ -1,18 +1,17 @@ # Represents a specialty. One of the following attributes MUST # be set when using this model: # -# * doctor_id -# * lawyer_id +# * doctor_id +# * lawyer_id # # This model has the following attributes: # -# * id -# * specialty_name: The name of this specialty. Will be normalized by Avvo. -# * specialty_id: The id of the normalized specialty, when known -# * specialty_percent: The percent of time this professional spends in this specialty -# * specialty_start_date: When this professional started practicing this specialty. -# * number_cases_handled: The number of cases handled within this specialty -# * description: Additional information about this specialty. +# * id +# * specialty_name: The name of this specialty. +# * specialty_percent: The percent of time this professional spends in this specialty +# * specialty_start_date: When this professional started practicing this specialty. +# * number_cases_handled: The number of cases handled within this specialty +# * description: Additional information about this specialty. # class AvvoApi::Specialty < AvvoApi::Base belongs_to :lawyer diff --git a/lib/avvo_api/version.rb b/lib/avvo_api/version.rb index 28b88ae..ec730f9 100644 --- a/lib/avvo_api/version.rb +++ b/lib/avvo_api/version.rb @@ -1,3 +1,3 @@ module AvvoApi - VERSION = "0.0.1" + VERSION = "0.0.1" # :nodoc: end