datacentred 0.1.1pre → 1.1.1

data/lib/datacentred/model/usage.rb

@@ -1,14 +1,21 @@
 module Datacentred
   module Model
-    class Usage < OpenStruct
-      def initialize(params)
-        params.delete("links")
-        # params["last_updated_at"] = Time.parse params["last_updated_at"]
-        super(params)
-      end
-
-      def self.show(year, month)
-        Request::Usage.show(year, month)["projects"].map{ |project| new(project) }
+    # Usage data for a given month/year.
+    #
+    # Data is updated every few hours for the current month.
+    #
+    # @attr [Time] last_updated_at
+    # @attr [[Hash]] projects
+    class Usage < Base
+      # Retrieve account usage data for a given year/month.
+      #
+      # @param [Integer] year The year.
+      # @param [Integer] month The month.
+      # @raise [Errors::NotFound] Raised if no usage data found for given year/month pair.
+      # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+      # @return [Usage] Usage for given year/month pair.
+      def self.find(year, month)
+        new Request::Usage.show year, month
       end
     end
   end

data/lib/datacentred/model/user.rb

@@ -1,31 +1,63 @@
 module Datacentred
   module Model
-    class User < OpenStruct
-      def initialize(params)
-        params.delete("links")
-        params["created_at"] = Time.parse params["created_at"]
-        params["updated_at"] = Time.parse params["updated_at"]
-        super(params)
-      end
-
-      def self.all
-        Request::Users.list.map { |user| new(user) }
-      end
+    # A user on your DataCentred account.
+    #
+    # Users are team members with the ability to log into your DataCentred account.
+    #
+    # All users created in your DataCented account are backed by a corresponding user in OpenStack's identity service (Keystone).
+    class User < Base
+      class << self
+        # Create a new user.
+        #
+        # @param [Hash] params User attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [User] New user.
+        def create(params)
+          new Request::Users.create params
+        end
 
-      def self.find(id)
-        new Request::Users.show(id)
-      end
+        # List all available users.
+        #
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[User]] A collection of all users on this account.
+        def all
+          Request::Users.list.map {|user| new user }
+        end
 
-      def self.create(params)
-        new Request::Users.create(params)
-      end
+        # Find a user by unique ID.
+        #
+        # @param [String] id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [User] The user, if it exists.
+        def find(id)
+          new Request::Users.show id
+        end
 
-      def self.update(id, params)
-        new Request::Users.update(id, params)
-      end
+        # Update a user by unique ID.
+        #
+        # @param [String] id The unique identifier for this user.
+        # @param [Hash] params User attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::NotFound] Raised if the user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [User] The updated user.
+        def update(id, params)
+          new Request::Users.update id, params
+        end
 
-      def self.delete(id)
-        Request::Users.destroy(id)
+        # Permanently remove the specified user.
+        #
+        # @param [String] id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the user couldn't be found.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the specified user.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Boolean] Confirms the user was destroyed.
+        def destroy(id)
+          Request::Users.destroy id
+          true
+        end
       end
     end
   end

data/lib/datacentred/model/version.rb

@@ -1,13 +1,22 @@
 module Datacentred
   module Model
-    class Version < OpenStruct
-      def initialize(params)
-        params.delete("links")
-        super(params)
-      end
-
-      def self.show
-        Request::Versions.list.map { |version| new(version) }
+    # An API version currently available for use.
+    #
+    #   This method does not require authentication.
+    #
+    # An API version may be:
+    # * *CURRENT* - The latest supported version.
+    # * *SUPPORTED* - A supported older version.
+    # * *DEPRECATED* - Currently supported but soon to be retired.
+    #
+    # @attr [Integer] id
+    # @attr [String] status
+    class Version < Base
+      # List all available API versions
+      #
+      # @return [[Version]] Currently available versions of the API.
+      def self.all
+        Request::Versions.list.map {|version| new version }
       end
     end
   end

data/lib/datacentred/request/base.rb

@@ -1,46 +1,83 @@
 module Datacentred
   module Request
-    API_BASE_URL = 'https://my.datacentred.io'
-
+    # Base class for all API requests.
+    #
+    # Uses the Faraday library for HTTP interactions.
     class Base
+      class << self
+        # Access a resource via HTTP GET.
+        #
+        # @param [String] path Desired server path.
+        # @raise [Errors::Error] Raised if the server returns a non 2xx error code.
+        # @return [Object] Parsed server response body.
+        def get(path)
+          action :get, path
+        end
 
-      def self.get(url, payload=nil)
-        response = Datacentred::Response.new(conn.get(url, payload))
-        response.body
-      end
+        # Access a resource via HTTP POST.
+        #
+        # @param [String] path Desired server path.
+        # @param [Object] payload JSON serializable object.
+        # @raise [Errors::Error] Raised if the server returns a non 2xx error code.
+        # @return [Object] Parsed server response body.
+        def post(path, payload=nil)
+          action :post, path, payload
+        end
 
-      def self.post(url, payload=nil)
-        response = Datacentred::Response.new(conn.post(url, payload))
-        response.body
-      end
+        # Access a resource via HTTP PUT.
+        #
+        # @param [String] path Desired server path.
+        # @param [Object] payload JSON serializable object.
+        # @raise [Errors::Error] Raised if the server returns a non 2xx error code.
+        # @return [Object] Parsed server response body.
+        def put(path, payload=nil)
+          action :put, path, payload
+        end
 
-      def self.put(url, payload=nil)
-        response = Datacentred::Response.new(conn.put(url, payload))
-        response.body
-      end
+        # Access a resource via HTTP DELETE.
+        #
+        # @param [String] path Desired server path.
+        # @raise [Errors::Error] Raised if the server returns a non 2xx error code.
+        # @return [nil] Returns nil on success.
+        def delete(path)
+          action :delete, path
+        end
 
-      def self.delete(url, payload=nil)
-        response = Datacentred::Response.new(conn.delete(url, payload))
-        response.body
-      end
+        private
 
-      private
+        def action(verb, path, payload=nil)
+          params = [path, payload&.to_json].compact
+          response = Datacentred::Response.new connection.send verb, *params
+          response.body
+        end
 
-      def self.conn
-        Faraday.new(:url => API_BASE_URL) do |faraday|
-          faraday.path_prefix = "/api/"
-          faraday.request  :url_encoded
-          faraday.headers['Accept'] = "application/vnd.datacentred.api+json; version=1"
-          faraday.headers['Authorization'] = "Token token=#{credentials}"
-          faraday.headers['Content-Type'] = 'application/json'
-          faraday.adapter  Faraday.default_adapter
+        def connection
+          Faraday.new(url: base_url) do |faraday|
+            faraday.request :url_encoded
+            faraday.adapter Faraday.default_adapter
+            faraday.headers['Accept']        = "#{accept_type}; version=#{api_version}"
+            faraday.headers['Authorization'] = "Token token=#{credentials}"
+            faraday.headers['Content-Type']  = "application/json"
+            faraday.path_prefix              = "/api/"
+          end
         end
-      end
 
-      def self.credentials
-        "#{Datacentred.access_key}:#{Datacentred.secret_key}"
-      end
+        def accept_type
+          "application/vnd.datacentred.api+json"
+        end
+
+        def api_version
+          "1".freeze
+        end
 
+        def base_url
+          "https://my.datacentred.io"
+        end
+
+        def credentials
+          [Datacentred.access_key, Datacentred.secret_key].join ":"
+        end
+      end
     end
   end
 end

data/lib/datacentred/request/projects.rb

@@ -1,37 +1,105 @@
 module Datacentred
   module Request
+    # RESTful API requests for the projects endpoints.
     class Projects < Base
+      class << self
+        # Create a new project.
+        #
+        #   POST /api/projects
+        #
+        # @param [Hash] params Project attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Hash] New project.
+        def create(params)
+          post('projects', 'project' => params)['project']
+        end
 
-      def self.create(payload={})
-        post('projects', payload.to_json)['project']
-      end
-
-      def self.list
-        get('projects')['projects']
-      end
+        # List all available projects.
+        #
+        #   GET /api/projects
+        #
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Hash]] A collection of all projects on this account.
+        def list
+          get('projects')['projects']
+        end
 
-      def self.show(id)
-        get("projects/#{id}")['project']
-      end
+        # Find a project by unique ID.
+        #
+        #   GET /api/projects/ead738d9f894bed9
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::NotFound] Raised if the project couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Hash] The project, if it exists.
+        def show(id)
+          get("projects/#{id}")['project']
+        end
 
-      def self.update(id, payload={})
-        put("projects/#{id}", payload.to_json)['project']
-      end
+        # Update a project by unique ID.
+        #
+        #   PUT /api/projects/ead738d9f894bed9
+        #
+        # @param [String] id The unique identifier for this project.
+        # @param [Hash] params Project attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::NotFound] Raised if the project could not be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Hash] The updated project.
+        def update(id, params)
+          put("projects/#{id}", 'project' => params)['project']
+        end
 
-      def self.destroy(id)
-        delete("projects/#{id}")
-      end
+        # Permanently remove the specified project.
+        #
+        #   DELETE /api/projects/ead738d9f894bed9
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::NotFound] Raised if the project couldn't be found.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the specified project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [nil] Confirms the user was destroyed.
+        def destroy(id)
+          delete("projects/#{id}")
+        end
 
-      def self.list_users(id)
-        get("projects/#{id}/users")['users']
-      end
+        # List all users assigned to this project.
+        #
+        #   GET /api/projects/ead738d9f894bed9/users
+        #
+        # @param [String] id The unique identifier for this project.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Hash]] A collection of the project's users.
+        def list_users(id)
+          get("projects/#{id}/users")['users']
+        end
 
-      def self.add_user(project_id, user_id)
-        put("projects/#{project_id}/users/#{user_id}")
-      end
+        # Add a new user to this project, giving them access to it via OpenStack.
+        #
+        #   PUT /api/projects/ead738d9f894bed9/users/82fa8de8f09102cc
+        #
+        # @param [String] project_id The unique identifier for this project.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the project or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [nil] Confirms the user was added (or is already present).
+        def add_user(project_id, user_id)
+          put("projects/#{project_id}/users/#{user_id}")
+        end
 
-      def self.remove_user(project_id, user_id)
-        delete("projects/#{project_id}/users/#{user_id}")
+        # Remove user from this project, revoking their access to it on OpenStack.
+        #
+        #   DELETE /api/projects/ead738d9f894bed9/users/82fa8de8f09102cc
+        #
+        # @param [String] project_id The unique identifier for this project.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if project or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [nil] Confirms that user was removed (or is already absent).
+        def remove_user(project_id, user_id)
+          delete("projects/#{project_id}/users/#{user_id}")
+        end
       end
     end
   end

data/lib/datacentred/request/roles.rb

@@ -1,37 +1,105 @@
 module Datacentred
   module Request
+    # RESTful API requests for the roles endpoints.
     class Roles < Base
+      class << self
+        # Create a new role.
+        #
+        #   POST /api/roles
+        #
+        # @param [Hash] params Role attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Hash] New role.
+        def create(params)
+          post('roles', 'role' => params)['role']
+        end
 
-      def self.create(payload={})
-        post('roles', payload.to_json)['role']
-      end
-
-      def self.list
-        get('roles')['roles']
-      end
+        # List all available roles.
+        #
+        #   GET /api/roles
+        #
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Hash]] A collection of all roles on this account.
+        def list
+          get('roles')['roles']
+        end
 
-      def self.show(id)
-        get("roles/#{id}")['role']
-      end
+        # Find a role by unique ID.
+        #
+        #   GET /api/roles/ea894bed9d738d9f
+        #
+        # @param [String] id The unique identifier for this role.
+        # @raise [Errors::NotFound] Raised if the role couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Hash] The role, if it exists.
+        def show(id)
+          get("roles/#{id}")['role']
+        end
 
-      def self.update(id, payload={})
-        put("roles/#{id}", payload.to_json)['role']
-      end
+        # Update a role by unique ID.
+        #
+        #   PUT /api/roles/ea894bed9d738d9f
+        #
+        # @param [String] id The unique identifier for this role.
+        # @param [Hash] params Role attributes.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the supplied attributes.
+        # @raise [Errors::NotFound] Raised if the role doesn't exist.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [Hash] The updated role.
+        def update(id, params)
+          put("roles/#{id}", 'role' => params)['role']
+        end
 
-      def self.destroy(id)
-        delete("roles/#{id}")
-      end
+        # Permanently remove the specified role.
+        #
+        #   DELETE /api/roles/ea894bed9d738d9f
+        #
+        # @param [String] id The unique identifier for this role.
+        # @raise [Errors::NotFound] Raised if the role couldn't be found.
+        # @raise [Errors::UnprocessableEntity] Raised if validations fail for the specifed role.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [nil] Confirms the role was destroyed.
+        def destroy(id)
+          delete("roles/#{id}")
+        end
 
-      def self.list_users(role_id)
-        get("roles/#{role_id}/users")['users']
-      end
+        # List all users assigned to this role.
+        #
+        #   GET /api/roles/ea894bed9d738d9f/users
+        #
+        # @param [String] role_id The unique identifier for this role.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [[Hash]] A collection of the role's users.
+        def list_users(role_id)
+          get("roles/#{role_id}/users")['users']
+        end
 
-      def self.add_user(role_id, user_id)
-        put("roles/#{role_id}/users/#{user_id}")
-      end
+        # Add new user to this role, giving them the associated permissions.
+        #
+        #   PUT /api/roles/ea894bed9d738d9f/users/82fa8de8f09102cc
+        #
+        # @param [String] role_id The unique identifier for this role.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the role or user couldn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [nil] Confirms that user was added (or is already present).
+        def add_user(role_id, user_id)
+          put("roles/#{role_id}/users/#{user_id}")
+        end
 
-      def self.remove_user(role_id, user_id)
-        delete("roles/#{role_id}/users/#{user_id}")
+        # Remove user from this role, revoking the associated permissions.
+        #
+        #   DELETE /api/roles/ea894bed9d738d9f/users/82fa8de8f09102cc
+        #
+        # @param [String] role_id The unique identifier for this role.
+        # @param [String] user_id The unique identifier for this user.
+        # @raise [Errors::NotFound] Raised if the role or user coundn't be found.
+        # @raise [Errors::Unauthorized] Raised if credentials aren't valid.
+        # @return [nil] Confirms that user was removed (or is already absent).
+        def remove_user(role_id, user_id)
+          delete("roles/#{role_id}/users/#{user_id}")
+        end
       end
     end
   end