base.rb in conjur-api-4.15.0

- old
+ new

@@ -33,35 +33,11 @@
 require 'conjur/cast'
 
 module Conjur
   # NOTE: You have to put all 'class level' api docs here, because YARD is stoopid :-(
 
-  # This class provides access to Conjur services
-  # **TODO MOAR**
-  #
-  # # Conjur Services
-  #
-  # ### Public Keys Service
-  # The {http://developer.conjur.net/reference/services/pubkeys Conjur Public Keys} service provides a
-  # simple database of public keys with access controlled by Conjur.  Reading a user's public keys requires
-  # no authentication at all -- the user's public keys are public information, after all.
-  #
-  # Adding or deleting a public key may only be done if you have permission to update the *public keys
-  # resource*, which is created when the appliance is launched, and has a resource id
-  # `'<organizational account>:service:pubkeys-1.0/public-keys'`.  The appliance also comes with a Group named
-  # `'pubkeys-1.0/key-managers'` that has this permission.  Rather than granting each user permission to
-  # modify the public keys database, you should consider adding users to this group.
-  #
-  # A very common use case is {http://developer.conjur.net/tutorials/ssh public key management for SSH}
-  #
-  #
-  # ### Audit Service
-  #
-  # The {http://developer.conjur.net/reference/services/audit Conjur Audit Service} allows you to
-  # fetch audit records.
-  #
-  # Generally you will need to have *at least one* privilege on the subject of an event in order to see it.
+  # This class provides access to the Conjur services.
   class API
     include Escape
     include LogSource
     include StandardMethods
     include Cast
@@ -182,40 +158,65 @@
       @api_key = api_key
       @token = token
 
       raise "Expecting ( username and api_key ) or token" unless ( username && api_key ) || token
     end
-    
+
+    #@!attribute [r] api_key
+    # The api key used to create this instance.  This is only present when you created the api with {Conjur::API.new_from_key}.#
+    #
+    # @return [String] the api key, or nil if this instance was created from a token.
     attr_reader :api_key
 
+    # The name of the user as which this api instance is authenticated.  This is available whether the api
+    # instance was created from credentials or an authentication token.
     #
+    # @return [String] the login of the current user.
     def username
       @username || @token['data']
     end
 
-
+    # @api private
+    # used to delegate to host providing subclasses.
+    # @return [String] the host
     def host
       self.class.host
     end
 
+    # The token used to authenticate requests made with the api.  The token will be fetched
+    # if it hasn't already, or if it has expired.  Accordingly, this method may raise a RestClient::Unauthorized
+    # exception if the credentials are invalid.
+    #
+    # @note calling this method on an {Conjur::API} instance created with {Conjur::API.new_from_token} will have
+    # undefined behavior if the token is expired.
+    #
+    # @return [Hash] the authentication token as a Hash
+    # @raise [RestClient::Unauthorized] if the username and api key are invalid.
     def token
       @token = nil unless token_valid?
 
       @token ||= Conjur::API.authenticate(@username, @api_key)
 
       fail "obtained token is invalid" unless token_valid? # sanity check
 
       return @token
     end
-    
-    # Authenticate the username and api_key to obtain a request token.
-    # Tokens are cached by username for a short period of time.
+
+    # Credentials that can be merged with options to be passed to `RestClient::Resource` HTTP request methods.
+    # These include a username and an Authorization header containing the authentication token.
+    #
+    # @return [Hash] the options.
+    # @raise [RestClient::Unauthorized] if fetching the token fails.
+    # @see {#token}
     def credentials
       { headers: { authorization: "Token token=\"#{Base64.strict_encode64 token.to_json}\"" }, username: username }
     end
 
     private
 
+    # Check to see if @token is defined, and whether it's expired
+    #
+    # @return [Boolean] whether or not the token is valid.
     def token_valid?
       return false unless @token
       
       # Actual token expiration is 8 minutes, but why cut it so close
       expiration = 5.minutes