dnsimple 2.0.0.alpha4 → 2.0.0.alpha5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29282f721205ff41ca5aacb60da1ea9b1034439b
-  data.tar.gz: a5ecddeeb95166108c8e94862797901eb8cae133
+  metadata.gz: cf0e539a6bca86d40181c2d20b69ca34f8696fdd
+  data.tar.gz: c96cf74c57c17745f3c035dc0a38c8719c17c622
 SHA512:
-  metadata.gz: 31918228b994c55090c59df96764efc6c5de00b4124629f383f580740c9209a28354a35481c63aab0cf4400b2051b40f844412ee363a6a8990df6aea133ae873
-  data.tar.gz: 94bd0968025293dfc93acf35834ca3b119c7969bb99acf50854c7db73f8dccfa000d4cf4fde257db4d790f561a4c039e274131c6de81dae970cbc673a9139059
+  metadata.gz: b6179bd9c041410c27fd7550745b4a2fe1cca9ecfe193cfca4526064def95cf1817f4f7748baf1aa772671c444915c1ea3c0d77b508e3e7dda84a7bed33c9bd8
+  data.tar.gz: 6f1a9ce4b9cd77aa33fbb640e3e1e2613f6c17aeae83098caf53334a514635377850625a9fe4970c1a38beaa74040460aa1de8c9a74be53c519e343b40c19964

data/README.markdown

@@ -31,15 +31,35 @@ client = Dnsimple::Client.new(username: 'YOUR_USERNAME', api_token: 'YOUR_TOKEN'
 user = client.users.user
 puts "My email is #{user.email}"
 
-# Get a list of your domains
+
+# List your domains
 domains = client.domains.list
 domains.each do |domain|
   puts "Domain: %s (id: %d)" % [domain.name, domain.id]
 end
 
 # Create a domain
-domain = client.domains.create("example.com")
+domain = client.domains.create(name: "example.com")
+puts "Domain: %s (id: %d)" % [domain.name, domain.id]
+
+# Get a domain
+domain = client.domains.domain("example.com")
 puts "Domain: %s (id: %d)" % [domain.name, domain.id]
+
+
+# Create a domain record
+record = client.domains.create_record("example.com", record_type: "A", name: "www", content: "127.0.0.1")
+puts "Record: %s (id: %d)" % [record.name, record.id]
+
+# Get a domain record
+record = client.domains.record("example.com", 1234)
+puts "Record: %s (id: %d)" % [record.name, record.id]
+
+# List domain records
+records = client.domains.records("example.com")
+records.each do |record|
+  puts "Record: %s (id: %d)" % [record.name, record.id]
+end
 ```
 
 For the full library documentation visit http://rubydoc.info/gems/dnsimple

data/UPGRADING.markdown

@@ -0,0 +1,102 @@
+# Upgrading to v2.0
+
+v2.0 is a major upgrade over v1.x and is not backward compatible.
+
+The client has been completely rewritten from scratch to provide a more consistent interface
+and take advantage of Ruby 1.9.3 and Ruby 2.0.
+
+If you are upgrading your code from v1.x, here's the major changes you should be aware of.
+
+
+1.  The client is now an instance.
+
+    All the API calls are performed within the scope of an instance, rather than a class,
+    making it possible to pass the client around, write thread-safe code and create multiple client instances
+    with different API credentials for a multi-environment application.
+
+    ```ruby
+    # v1
+    DNSimple::Client.username   = 'YOUR_USERNAME'
+    DNSimple::Client.password   = 'YOUR_PASSWORD'
+    domain = DNSimple::Domain.find("example.com")
+
+    # v2
+    client = Dnsimple::Client.new(username: 'YOUR_USERNAME', password: 'YOUR_PASSWORD')
+    domain = client.domains.domain("example.com")
+    ```
+
+1.  API call responses are now simple struct-like objects, rather Model-like objects.
+
+    ```ruby
+    domain = client.domains.domain("example.com")
+    # => Dnsimple::Struct::Domain
+    ```
+
+    A struct-like object is designed to be a simple container of key/value attributes,
+    as opposite to a fully-features instance you can interact with.
+
+1.  API methods are now defined as methods of the client instance.
+
+    This is a consequence (or the cause, depending on the POV) of the previous point. It is no longer possible to call
+    persistence methods on an object returned from the API, as it was in v1.
+
+    ```ruby
+    record = client.domains.record("example.com", 1)
+    # this will fail
+    record.name = "www"
+    record.update
+    ```
+
+    Instead, treat the object a simple read-only container. If you need to manipulate a Record, Domain or another instance,
+    write your own object that encapsulate the desired persistence behavior.
+
+    Here's a very simple example.
+
+    ```ruby
+    class DnsimpleRecord
+      def self.find(client, domain, record_id)
+        client.record(domain, record_id)
+      end
+
+      def self.create(client, domain, attributes)
+        new(client.create_record(domain, attributes))
+      end
+
+      def initialize(client, instance)
+        @client   = client
+        @instance = instance
+      end
+
+      def update_ip(ip)
+        @client.update_record(@instance.domain_id, @instance.record_id, content: ip)
+      end
+    end
+    ```
+
+    Although this approach seems more verbose at first glance, it encourages the encapsulation of your application logic
+    inside custom objects, rather than promoting the patching of the core library objects.
+
+    Moreover, we found that in most cases developers need access to a very limited set of operations
+    rather all the possible API methods attached to a resource. And it's likely you already have a model in your application,
+    what you need is just a simple way to interact with the third-party DNSimple application.
+
+    Last but not least, this approach guarantees that if you want to alter the state of an object and you already know
+    its id, you don't need to perform a #find call to instantiate an object to call the update on:
+
+    ```ruby
+    # version 1
+    record = Dnsimple::Record.find("example.com", 12)
+    record.name = "updated"
+    record.content = "127.0.0.1"
+    record.update
+
+    # version 2
+    record = Dnsimple::Record.find("example.com", 12)
+    record.update(name: "updated", content: "127.0.0.1")
+    ```
+
+    Instead, simply execute
+
+    ```ruby
+    client.domains.update_record("example.com", 12, name: "updated", content: "127.0.0.1")
+    ```

data/lib/dnsimple/client.rb

@@ -60,7 +60,7 @@ module Dnsimple
     # @param  [Hash] options Query and header params for request
     # @return [HTTParty::Response]
     def get(path, options = {})
-      request :get, path, options
+      execute :get, path, options
     end
 
     # Make a HTTP POST request.
@@ -69,7 +69,7 @@ module Dnsimple
     # @param  [Hash] options Body and header params for request
     # @return [HTTParty::Response]
     def post(path, options = {})
-      request :post, path, options
+      execute :post, path, options
     end
 
     # Make a HTTP PUT request.
@@ -78,7 +78,7 @@ module Dnsimple
     # @param  [Hash] options Body and header params for request
     # @return [HTTParty::Response]
     def put(path, options = {})
-      request :put, path, options
+      execute :put, path, options
     end
 
     # Make a HTTP DELETE request.
@@ -87,26 +87,22 @@ module Dnsimple
     # @param  [Hash] options Query and header params for request
     # @return [HTTParty::Response]
     def delete(path, options = {})
-      request :delete, path, options
+      execute :delete, path, options
     end
 
 
-    # Make a HTTP request.
+    # Executes a request, validates and returns the response.
     #
     # @param  [String] method The HTTP method
     # @param  [String] path The path, relative to {#api_endpoint}
     # @param  [Hash] options Query and header params for request
     # @return [HTTParty::Response]
-    def request(method, path, data, options = {})
-      if data.is_a?(Hash)
-        options[:query]   = data.delete(:query)   if data.key?(:query)
-        options[:headers] = data.delete(:headers) if data.key?(:headers)
-      end
-      if !data.empty?
-        options[:body] = data
-      end
-
-      response = HTTParty.send(method, api_endpoint + path, Extra.deep_merge!(base_options, options))
+    # @raise  [RequestError]
+    # @raise  [NotFoundError]
+    # @raise  [AuthenticationFailed]
+    # @raise  [TwoFactorAuthenticationRequired]
+    def execute(method, path, data, options = {})
+      response = request(method, path, data, options)
 
       case response.code
       when 200..299
@@ -114,13 +110,38 @@ module Dnsimple
       when 401
         raise (response.headers[HEADER_OTP_TOKEN] == "required" ? TwoFactorAuthenticationRequired : AuthenticationFailed), response["message"]
       when 404
-        raise RecordNotFound.new(response)
+        raise NotFoundError.new(response)
       else
         raise RequestError.new(response)
       end
     end
 
 
+    # Make a HTTP request.
+    #
+    # This method doesn't validate the response and never raise errors
+    # even in case of HTTP error codes, except for connection errors raised by
+    # the underlying HTTP client.
+    #
+    # Therefore, it's up to the caller to properly handle and validate the response.
+    #
+    # @param  [String] method The HTTP method
+    # @param  [String] path The path, relative to {#api_endpoint}
+    # @param  [Hash] options Query and header params for request
+    # @return [HTTParty::Response]
+    def request(method, path, data, options = {})
+      if data.is_a?(Hash)
+        options[:query]   = data.delete(:query)   if data.key?(:query)
+        options[:headers] = data.delete(:headers) if data.key?(:headers)
+      end
+      if !data.empty?
+        options[:body] = data
+      end
+
+      HTTParty.send(method, api_endpoint + path, Extra.deep_merge!(base_options, options))
+    end
+
+
     # @return [String] Base URL for API requests.
     def api_endpoint
       File.join(@api_endpoint, "")

data/lib/dnsimple/client/certificates.rb

@@ -10,14 +10,16 @@ module Dnsimple
       # @param  [Hash] options
       #
       # @return [Array<Struct::Certificate>]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def list(domain, options = {})
+      def certificates(domain, options = {})
         response = client.get("v1/domains/#{domain}/certificates", options)
 
         response.map { |r| Struct::Certificate.new(r["certificate"]) }
       end
 
+      alias :list :certificates
+
       # Gets a certificate for a domain.
       #
       # @see http://developer.dnsimple.com/domains/certificates/#get
@@ -26,9 +28,9 @@ module Dnsimple
       # @param  [Fixnum] certificate_id The certificate ID.
       #
       # @return [Struct::Certificate]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def find(domain, certificate_id)
+      def certificate(domain, certificate_id)
         response = client.get("v1/domains/#{domain}/certificates/#{certificate_id}")
 
         Struct::Certificate.new(response["certificate"])
@@ -54,7 +56,7 @@ module Dnsimple
       # @param  [Fixnum] contact_id The ID of the contact associated to the certificate.
       #
       # @return [Struct::Certificate]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def purchase(domain, name, contact_id, options = {})
         options  = Extra.deep_merge(options, { certificate: { name: name, contact_id: contact_id }})
@@ -69,7 +71,7 @@ module Dnsimple
       # @param  [Fixnum] certificate_id The certificate ID.
       #
       # @return [Struct::Certificate]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def configure(domain, certificate_id)
         response = client.put("v1/domains/#{domain}/certificates/#{certificate_id}/configure")
@@ -84,7 +86,7 @@ module Dnsimple
       # @param  [Fixnum] email The approver email.
       #
       # @return [Struct::Certificate]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def submit(domain, certificate_id, email)
         options = { certificate: { approver_email: email }}

data/lib/dnsimple/client/contacts.rb

@@ -8,12 +8,14 @@ module Dnsimple
       #
       # @return [Array<Struct::Contact>]
       # @raise  [RequestError] When the request fails.
-      def list
+      def contacts
         response = client.get("v1/contacts")
 
         response.map { |r| Struct::Contact.new(r["contact"]) }
       end
 
+      alias :list :contacts
+
       # Creates a contact in the account.
       #
       # @see http://developer.dnsimple.com/contacts/#create
@@ -37,9 +39,9 @@ module Dnsimple
       # @param  [Fixnum] contact The contact id.
       #
       # @return [Struct::Contact]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def find(contact)
+      def contact(contact)
         response = client.get("v1/contacts/#{contact}")
 
         Struct::Contact.new(response["contact"])
@@ -53,7 +55,7 @@ module Dnsimple
       # @param  [Hash] attributes
       #
       # @return [Struct::Contact]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def update(contact, attributes = {})
         options  = { contact: attributes }
@@ -71,7 +73,7 @@ module Dnsimple
       # @param  [Fixnum] contact The contact id.
       #
       # @return [void]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def delete(contact)
         client.delete("v1/contacts/#{contact}")

data/lib/dnsimple/client/domains.rb

@@ -8,12 +8,14 @@ module Dnsimple
       #
       # @return [Array<Struct::Domain>]
       # @raise  [RequestError] When the request fails.
-      def list(options = {})
+      def domains(options = {})
         response = client.get("v1/domains", options)
 
         response.map { |r| Struct::Domain.new(r["domain"]) }
       end
 
+      alias :list :domains
+
       # Gets a domain from the account.
       #
       # @see http://developer.dnsimple.com/domains/#get
@@ -21,9 +23,9 @@ module Dnsimple
       # @param  [#to_s] domain The domain id or domain name.
       #
       # @return [Struct::Domain]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def find(domain)
+      def domain(domain)
         response = client.get("v1/domains/#{domain}")
 
         Struct::Domain.new(response["domain"])
@@ -54,7 +56,7 @@ module Dnsimple
       # @param  [#to_s] domain The domain id or domain name.
       #
       # @return [void]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def delete(domain)
         client.delete("v1/domains/#{domain}")

data/lib/dnsimple/client/domains_forwards.rb

@@ -9,9 +9,9 @@ module Dnsimple
       # @param  [#to_s] domain The domain id or domain name.
       #
       # @return [Array<Struct::EmailForward>]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def list_email_forwards(domain)
+      def email_forwards(domain)
         response = client.get("v1/domains/#{domain}/email_forwards")
 
         response.map { |r| Struct::EmailForward.new(r["email_forward"]) }
@@ -25,7 +25,7 @@ module Dnsimple
       # @param  [Hash] attributes
       #
       # @return [Struct::EmailForward]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def create_email_forward(domain, attributes = {})
         Extra.validate_mandatory_attributes(attributes, [:from, :to])
@@ -43,9 +43,9 @@ module Dnsimple
       # @param  [Fixnum] forward The forward id.
       #
       # @return [Struct::EmailForward]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def find_email_forward(domain, forward)
+      def email_forward(domain, forward)
         response = client.get("v1/domains/#{domain}/email_forwards/#{forward}")
 
         Struct::EmailForward.new(response["email_forward"])
@@ -59,7 +59,7 @@ module Dnsimple
       # @param  [Fixnum] forward The forward id.
       #
       # @return [void]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def delete_email_forward(domain, forward)
         client.delete("v1/domains/#{domain}/email_forwards/#{forward}")

data/lib/dnsimple/client/domains_records.rb

@@ -10,9 +10,9 @@ module Dnsimple
       # @param  [Hash] options
       #
       # @return [Array<Struct::Record>]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def list_records(domain, options = {})
+      def records(domain, options = {})
         response = client.get("v1/domains/#{domain}/records", options)
 
         response.map { |r| Struct::Record.new(r["record"]) }
@@ -26,7 +26,7 @@ module Dnsimple
       # @param  [Hash] attributes
       #
       # @return [Struct::Record]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def create_record(domain, attributes = {})
         Extra.validate_mandatory_attributes(attributes, [:name, :record_type, :content])
@@ -44,9 +44,9 @@ module Dnsimple
       # @param  [Fixnum] record The record id.
       #
       # @return [Struct::Record]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
-      def find_record(domain, record)
+      def record(domain, record)
         response = client.get("v1/domains/#{domain}/records/#{record}")
 
         Struct::Record.new(response["record"])
@@ -61,7 +61,7 @@ module Dnsimple
       # @param  [Hash] attributes
       #
       # @return [Struct::Record]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def update_record(domain, record, attributes = {})
         options  = { record: attributes }
@@ -78,7 +78,7 @@ module Dnsimple
       # @param  [Fixnum] record The record id.
       #
       # @return [void]
-      # @raise  [RecordNotFound]
+      # @raise  [NotFoundError]
       # @raise  [RequestError] When the request fails.
       def delete_record(domain, record)
         client.delete("v1/domains/#{domain}/records/#{record}")