grafana 0.8.2 → 1.0.0

data/lib/grafana/annotations.rb

@@ -1,39 +1,314 @@
 
 module Grafana
 
-  # http://docs.grafana.org/http_api/annotations/
+  # This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6.
+  # Annotations are saved in the Grafana database (sqlite, mysql or postgres).
+  #
+  # Annotations can be global annotations that can be shown on any dashboard by configuring an annotation
+  # data source - they are filtered by tags.
+  #
+  # Or they can be tied to a panel on a dashboard and are then only shown on that panel.
+  #
+  # original API Documentation can be found under: http://docs.grafana.org/http_api/annotations/
   #
   module Annotations
 
     # Find Annotations
     # http://docs.grafana.org/http_api/annotations/#find-annotations
-    # GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100
-    def find_annotation( params ); end
+    #
+    # @param [Hash] params
+    # @option params [Integer] from: epoch datetime in milliseconds. Optional.
+    # @option params [Integer] to: epoch datetime in milliseconds. Optional.
+    # @option params [Integer] limit: number. Optional - default is 10. Max limit for results returned.
+    # @option params [Integer] alert_id: number. Optional. Find annotations for a specified alert.
+    # @option params [Mixed] dashboard: number. Optional. Find annotations that are scoped to a specific dashboard
+    # @option params [Integer] panel_id: number. Optional. Find annotations that are scoped to a specific panel
+    # @option params [Array] tags: Optional. Use this to filter global annotations.
+    #                              Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel.
+    #                              To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g.
+    #
+    # @example
+    #    params = {
+    #      limit: 5,
+    #      tags: [ 'spec', 'test' ]
+    #    }
+    #    find_annotation( params )
+    #
+    # @return [Array]
+    #
+    def find_annotation( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      dashboard = validate( params, required: false, var: 'dashboard' )
+      from      = validate( params, required: false, var: 'from', type: Integer )
+      to        = validate( params, required: false, var: 'to', type: Integer )
+      limit     = validate( params, required: false, var: 'limit', type: Integer ) || 10
+      alert_id  = validate( params, required: false, var: 'alert_id', type: Integer )
+      panel_id  = validate( params, required: false, var: 'panel_id', type: Integer )
+      tags      = validate( params, required: false, var: 'tags', type: Array )
+
+      if( dashboard.is_a?(String) )
+
+        dashboard = search_dashboards( query: dashboard )
+
+        return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard) } if( dashboard.nil? || dashboard.dig('status').to_i != 200 )
+
+        dashboard = dashboard.dig('message').first unless( dashboard.nil? && dashboard.dig('status').to_i == 200 )
+        dashboard = dashboard.dig('id') unless( dashboard.nil? )
+
+        return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard) } if( dashboard.nil? )
+      end
+
+      api     = []
+      api << format( 'from=%s', from ) unless( from.nil? )
+      api << format( 'to=%s', to ) unless( to.nil? )
+      api << format( 'limit=%s', limit ) unless( limit.nil? )
+      api << format( 'alertId=%s', alert_id ) unless( alert_id.nil? )
+      api << format( 'panelId=%s', panel_id ) unless( panel_id.nil? )
+      api << format( 'dashboardId=%s', dashboard ) unless( dashboard.nil? )
+
+      unless( tags.nil? )
+        tags = tags.join( '&tags=' ) if( tags.is_a?( Array ) )
+        api << format( 'tags=%s', tags )
+      end
+      api = api.join( '&' )
+
+      endpoint = format( '/api/annotations/?%s' , api )
+
+      @logger.debug("Attempting to search for annotations (GET #{endpoint})") if @debug
+
+      get( endpoint )
+    end
 
     # Create Annotation
+    #
+    # Creates an annotation in the Grafana database.
+    # The dashboard_id and panel_id fields are optional.
+    # If they are not specified then a global annotation is created and can be queried in any dashboard that adds
+    # the Grafana annotations data source.
+    #
+    # When creating a region annotation the response will include both id and endId, if not only id.
+    #
     # http://docs.grafana.org/http_api/annotations/#create-annotation
     # POST /api/annotations
-    def create_annotation( params ); end
+    #
+    #
+    # @param [Hash] params
+    # @option params [Mixed] dashboard
+    # @option params [Integer] panel_id
+    # @option params [Integer] time:
+    # @option params [Integer] time_end:
+    # @option params [Boolean] region:
+    # @option params [Array] tags:
+    # @option params [String] text:
+    #
+    # @example
+    #    params = {
+    #      time: Time.now.to_i,
+    #      tags: [ 'spec', 'test' ],
+    #      text: 'test annotation'
+    #    }
+    #    create_annotation( params )
+    #
+    # @return [Hash]
+    #
+    def create_annotation( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      dashboard = validate( params, required: false, var: 'dashboard' )
+      panel_id  = validate( params, required: false, var: 'panel_id', type: Integer )
+      time      = validate( params, required: false, var: 'time', type: Integer ) || Time.now.to_i
+      time_end  = validate( params, required: false, var: 'time_end', type: Integer )
+      region    = validate( params, required: false, var: 'region', type: Boolean )
+      tags      = validate( params, required: true, var: 'tags', type: Array )
+      text      = validate( params, required: true, var: 'text', type: String )
+
+      if( dashboard.is_a?(String) )
+
+        dashboard = search_dashboards( query: dashboard )
+
+        return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard) } if( dashboard.nil? || dashboard.dig('status').to_i != 200 )
+
+        dashboard = dashboard.dig('message').first unless( dashboard.nil? && dashboard.dig('status').to_i == 200 )
+        dashboard = dashboard.dig('id') unless( dashboard.nil? )
+
+        return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard) } if( dashboard.nil? )
+      end
+
+      unless( time_end.nil? )
+        return { 'status' => 404, 'message' => format( '\'end_time\' can\'t be lower then \'time\'' ) } if( time_end < time )
+      end
+
+      endpoint = '/api/annotations'
+      payload = {
+        dashboardId: dashboard,
+        panelId: panel_id,
+        time: time,
+        timeEnd: time_end,
+        isRegion: region,
+        tags: tags,
+        text: text
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      post(endpoint, payload.to_json)
+    end
 
     # Create Annotation in Graphite format
+    #
+    # Creates an annotation by using Graphite-compatible event format.
+    # The when and data fields are optional.
+    # If when is not specified then the current time will be used as annotation's timestamp.
+    # The tags field can also be in prior to Graphite 0.10.0 format (string with multiple tags being separated by a space).
+    #
     # http://docs.grafana.org/http_api/annotations/#create-annotation-in-graphite-format
     # POST /api/annotations/graphite
-    def create_annotation_graphite( params ); end
+    #
+    # @param [Hash] params
+    # @option params [Integer] what
+    # @option params [Integer] when
+    # @option params [Array] tags
+    # @option params [String] data
+    #
+    # @example
+    #    params = {
+    #      what: 'spec test graphite annotation',
+    #      when: Time.now.to_i,
+    #      tags: [ 'spec', 'test' ],
+    #      data: 'test annotation'
+    #    }
+    #    create_annotation_graphite( params )
+    #
+    # @return [Hash]
+    #
+    def create_annotation_graphite( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      what      = validate( params, required: true , var: 'what', type: String )
+      time_when = validate( params, required: false, var: 'when', type: Integer ) || Time.now.to_i
+      tags      = validate( params, required: true , var: 'tags', type: Array )
+      data      = validate( params, required: false, var: 'data', type: String )
+
+      endpoint = '/api/annotations/graphite'
+      payload = {
+        what: what,
+        when: time_when,
+        tags: tags,
+        data: data
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      post(endpoint, payload.to_json)
+    end
 
     # Update Annotation
+    #
     # http://docs.grafana.org/http_api/annotations/#update-annotation
-    # PUT /api/annotations/:id
-    def update_annotation( params ); end
+    #
+    # @param [Hash] params
+    # @option params [Integer] annotation
+    # @option params [Integer] time
+    # @option params [Integer] time_end
+    # @option params [Boolean] region
+    # @option params [Array] tags
+    # @option params [String] text
+    #
+    # @example
+    #    params = {
+    #      annotation: 1,
+    #      tags: [ 'deployment' ],
+    #      text: 'git tag #1234'
+    #    }
+    #    update_annotation( params )
+    #
+    # @return [Hash]
+    #
+    def update_annotation( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      annotation_id = validate( params, required: true, var: 'annotation', type: Integer )
+      time      = validate( params, required: false, var: 'time', type: Integer )
+      time_end  = validate( params, required: false, var: 'time_end', type: Integer )
+      region    = validate( params, required: false, var: 'region', type: Boolean )
+      tags      = validate( params, required: false, var: 'tags', type: Array )
+      text      = validate( params, required: false, var: 'text', type: String )
+
+      unless( time_end.nil? )
+        return { 'status' => 404, 'message' => format( '\'end_time\' can\'t be lower then \'time\'' ) } if( time_end < time )
+      end
+
+      endpoint = format( '/api/annotations/%d', annotation_id)
+      payload = {
+        time: time,
+        timeEnd: time_end,
+        isRegion: region,
+        text: text,
+        tags: tags
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      put(endpoint, payload.to_json)
+    end
 
     # Delete Annotation By Id
+    #
+    # Deletes the annotation that matches the specified id.
+    #
     # http://docs.grafana.org/http_api/annotations/#delete-annotation-by-id
     # DELETE /api/annotation/:id
-    def delete_annotation( params ); end
+    #
+    # @param [Integer] annotation_id
+    #
+    # @example
+    #    delete_annotation( 1 )
+    #
+    # @return [Hash]
+    #
+    def delete_annotation( annotation_id )
+
+      raise ArgumentError.new(format('wrong type. user \'annotation_id\' must be an Integer, given \'%s\'', annotation_id.class.to_s)) unless( annotation_id.is_a?(Integer) )
+      raise ArgumentError.new('missing \'annotation_id\'') if( annotation_id.size.zero? )
+      raise ArgumentError.new('\'annotation_id\' can not be 0') if( annotation_id.zero? )
+
+      endpoint = format( '/api/annotation/%d', annotation_id )
+
+      delete(endpoint)
+    end
 
     # Delete Annotation By RegionId
+    #
+    # Deletes the annotation that matches the specified region id.
+    # A region is an annotation that covers a timerange and has a start and end time.
+    # In the Grafana database, this is a stored as two annotations connected by a region id.
+    #
     # http://docs.grafana.org/http_api/annotations/#delete-annotation-by-regionid
     # DELETE /api/annotation/region/:id
-    def delete_annotation_by_region( params ); end
+    #
+    # @param [Integer] region_id
+    #
+    # @example
+    #    delete_annotation_by_region( 1 )
+    #
+    # @return [Hash]
+    #
+    def delete_annotation_by_region( region_id )
+
+      raise ArgumentError.new(format('wrong type. user \'region_id\' must be an Integer, given \'%s\'', region_id.class.to_s)) unless( region_id.is_a?(Integer) )
+      raise ArgumentError.new('missing \'region_id\'') if( region_id.size.zero? )
+#       raise ArgumentError.new('\'region_id\' can not be 0') if( region_id.zero? )
+
+      endpoint = format( '/api/annotation/region/%d', region_id )
+
+      delete(endpoint)
+    end
 
   end
 

data/lib/grafana/client.rb

@@ -12,14 +12,22 @@ require_relative 'network'
 require_relative 'tools'
 require_relative 'admin'
 require_relative 'annotations'
+require_relative 'preferences'
 require_relative 'user'
 require_relative 'users'
+require_relative 'teams'
 require_relative 'datasource'
 require_relative 'organization'
 require_relative 'organizations'
 require_relative 'dashboard'
 require_relative 'dashboard_versions'
+require_relative 'dashboard_permissions'
 require_relative 'snapshot'
+require_relative 'alerts'
+require_relative 'folder'
+require_relative 'folder_permissions'
+require_relative 'folder_and_dashboard_search'
+require_relative 'playlist'
 
 # -------------------------------------------------------------------------------------------------------------------
 #
@@ -46,14 +54,22 @@ module Grafana
     include Grafana::Tools
     include Grafana::Admin
     include Grafana::Annotations
+    include Grafana::Preferences
     include Grafana::User
     include Grafana::Users
+    include Grafana::Teams
     include Grafana::Datasource
     include Grafana::Organization
     include Grafana::Organizations
     include Grafana::Dashboard
     include Grafana::DashboardVersions
+    include Grafana::DashboardPermissions
     include Grafana::Snapshot
+    include Grafana::Alerts
+    include Grafana::Folder
+    include Grafana::FolderPermissions
+    include Grafana::FolderSearch
+    include Grafana::Playlist
 
     attr_accessor :debug
 
@@ -98,6 +114,8 @@ module Grafana
       @http_headers       = settings.dig(:grafana, :http_headers)  || {}
       @debug              = settings.dig(:debug)                   || false
 
+      @headers            = {}
+
       raise ArgumentError.new('missing \'host\'') if( host.nil? )
 
       raise ArgumentError.new(format('wrong type. \'port\' must be an Integer, given \'%s\'', port.class.to_s)) unless( port.is_a?(Integer) )
@@ -107,11 +125,30 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'open_timeout\' must be an Integer, given \'%s\'', @open_timeout.class.to_s)) unless( @open_timeout.is_a?(Integer) )
 
       protocoll = ssl == true ? 'https' : 'http'
-      raise ArgumentError.new(format('wrong \'protocoll\'. only \'http\' or \'https\' allowed, given \'%s\'', protocoll)) if( %w[http https].include?(protocoll.downcase) == false )
 
       @url      = format( '%s://%s:%d%s', protocoll, host, port, url_path )
     end
 
+    # Get Settings
+    #
+    # http://docs.grafana.org/http_api/other/#get-settings
+    #
+    def settings
+      endpoint = '/api/frontend/settings'
+      @logger.debug("Getting all settings (GET #{endpoint})") if @debug
+      get(endpoint)
+    end
+
+
+    def version
+      s = settings
+      @version =  s.dig('buildInfo','version')
+      @major_version = @version.split('.').first.to_i
+
+      {version: @version, major_version: @major_version}
+    end
+
+
     def self.logger
       @@logger ||= defined?(Logging) ? Logging.logger : Logger.new(STDOUT)
     end

data/lib/grafana/dashboard.rb

@@ -2,59 +2,186 @@
 module Grafana
 
   # http://docs.grafana.org/http_api/dashboard/
+
+  # The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
+  #
+  # The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
+  # It's automatically generated if not provided when creating a dashboard. The uid allows having consistent URL's for
+  # accessing dashboards and when syncing dashboards between multiple Grafana installs, see dashboard provisioning for
+  # more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.
+  #
+  # The uid can have a maximum length of 40 characters.
+  #
+  # Deprecated resources
+  #  Please note that these resource have been deprecated and will be removed in a future release.
+  #
+  #  - Get dashboard by slug
+  #  - Delete dashboard by slug
+  #
+  #
   #
   module Dashboard
 
-
+    # http://docs.grafana.org/http_api/dashboard/#get-dashboard-by-slug
+    #  - Deprecated starting from Grafana v5.0.
+    #    Please update to use the new Get dashboard by uid resource instead
+    #
     # Get dashboard
-    # GET /api/dashboards/db/:slug
+    #
+    # Will return the dashboard given the dashboard slug.
+    # Slug is the url friendly version of the dashboard title.
+    # If there exists multiple dashboards with the same slug, one of them will be returned in the response.
+    #
+    # @example
+    #    dashboard('dashboard for many foo')
+    #
+    # @return [String]
+    #
     def dashboard( name )
 
       raise ArgumentError.new(format('wrong type. \'name\' must be an String, given \'%s\'', name.class.to_s)) unless( name.is_a?(String) )
       raise ArgumentError.new('missing name') if( name.size.zero? )
 
-#       raise ArgumentError.new('name must be an String') unless( name.is_a?(String) )
+#       v, mv = version.values
+#
+#       if( mv == 5)
+#         puts 'DEPRICATION WARNING'
+#         puts 'Grafana v5.0 use a new interal id/uid handling'
+#         puts 'This function works well with Grafana v4.x'
+#       end
 
       endpoint = format( '/api/dashboards/db/%s', slug(name) )
+      @logger.debug( "Attempting to get dashboard (GET #{endpoint})" ) if @debug
 
-      @logger.debug( "Attempting to get dashboard (GET /api/dashboards/db/#{name})" ) if @debug
+      get( endpoint )
+    end
+
+    # http://docs.grafana.org/http_api/dashboard/#get-dashboard-by-uid
+    #
+    # GET /api/dashboards/uid/:uid
+    # Will return the dashboard given the dashboard unique identifier (uid).
+    #
+    # Get dashboard
+    #
+    # Will return the dashboard given the dashboard unique identifier (uid).
+    #
+    # @example
+    #    dashboard('L42r6NWiz')
+    #
+    # @return [String]
+    #
+    def dashboard_by_uid( uid )
+
+      if( uid.is_a?(String) && uid.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. dashboard \'uid\' must be an String (for an title name) or an Integer (for an Datasource Id), given \'%s\'', uid.class.to_s))
+      end
+      raise ArgumentError.new('missing \'uid\'') if( uid.size.zero? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'uid has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters, but it is %s characters long', uid.length) } if( uid.length > 40 )
+
+      endpoint = format( '/api/dashboards/uid/%s', uid )
+      @logger.debug( "Attempting to get dashboard (GET #{endpoint})" ) if @debug
 
       get( endpoint )
     end
 
     # Create / Update dashboard
+    #
+    # Creates a new dashboard or updates an existing dashboard.
+    #
+    # @param [Hash] params
+    # @option params [Hash] dashboard The complete dashboard model
+    #  - dashboard.id - id = null to create a new dashboard.
+    #  - dashboard.uid - Optional unique identifier when creating a dashboard. uid = null will generate a new uid.
+    #  - folderId - The id of the folder to save the dashboard in.
+    #  - overwrite - Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
+    #  - message - Set a commit message for the version history.
+    # @option params [Boolean] overwrite (true)
+    #
+    # @example
+    #    params = {
+    #      dashboard: {
+    #        id: null,
+    #        uid: null,
+    #        title: 'Production Overview',
+    #        tags: [ 'templated' ],
+    #        timezone": 'browser',
+    #        rows: [
+    #          {
+    #          }
+    #        ],
+    #        'schemaVersion': 6,
+    #        'version': 0
+    #      },
+    #      folderId: 0,
+    #      overwrite: false,
+    #      message: 'created by foo'
+    #    }
+    #    create_dashboard( params )
+    #
+    # @return [Hash]
+    #
     # POST /api/dashboards/db
     def create_dashboard( params )
 
-      raise ArgumentError.new(format('wrong type. params must be an Hash, given %s', params.class.to_s ) ) unless( params.is_a?(Hash) )
-
-      title     = params.dig(:title)
-      dashboard = params.dig(:dashboard)
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-      # raise ArgumentError.new('missing title') if( title.nil? )
-      raise ArgumentError.new('missing dashboard') if( dashboard.nil? )
-      raise ArgumentError.new(format('wrong type. dashboard must be an Hash, given %s', dashboard.class.to_s ) ) unless( dashboard.is_a?(Hash) )
+      dashboard = validate( params, required: true , var: 'dashboard', type: Hash )
+      overwrite = validate( params, required: false, var: 'overwrite', type: Boolean ) || true
+      folder_id = validate( params, required: false, var: 'folderId' )
+      message   = validate( params, required: false, var: 'message', type: String )
 
-      endpoint = '/api/dashboards/db'
-      # title     = slug(title)
-
-      # dashboard = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
       dashboard = regenerate_template_ids( dashboard )
 
-      if( title.nil? )
-        db = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
-        title = db.dig('dashboard','title')
+      unless(folder_id.nil?)
+        f_folder = folder(folder_id)
+        return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_id) } if( f_folder.dig('status') != 200 )
+
+        folder_id = f_folder.dig('id')
       end
 
+      db = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
+      title = db.dig('dashboard','title')
+      uid   = db.dig('dashboard','uid')
+
+      return { 'status' => 404, 'message' => format( 'The template \'%s\' can\'t be create. The uid can have a maximum length of 40 characters, but it is %s characters long', title, uid.length) } if( ! uid.nil? && uid.length > 40 )
+
+      endpoint = '/api/dashboards/db'
+
+      payload = {
+        dashboard: db.dig('dashboard'),
+        overwrite: overwrite,
+        folderId: folder_id,
+        message: message
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
       @logger.debug("Creating dashboard: #{title} (POST /api/dashboards/db)") if @debug
 
-      post( endpoint, dashboard )
+      post( endpoint, payload.to_json )
     end
 
+    # http://docs.grafana.org/http_api/dashboard/#delete-dashboard-by-slug
+    #  - Deprecated starting from Grafana v5.0.
+    #    Please update to use the new Get dashboard by uid resource instead
+    #
     # Delete dashboard
-    # DELETE /api/dashboards/db/:slug
+    # Will delete the dashboard given the specified slug. Slug is the url friendly version of the dashboard title.
+    #
+    # @example
+    #    delete_dashboard('dashboard for many foo')
+    #
+    # @return [Hash]
+    #
     def delete_dashboard( name )
 
+      raise ArgumentError.new(format('wrong type. \'name\' must be an String, given \'%s\'', name.class.to_s)) unless( name.is_a?(String) )
+      raise ArgumentError.new('missing name') if( name.size.zero? )
+
       endpoint = format( '/api/dashboards/db/%s', slug(name) )
 
       @logger.debug("Deleting dashboard #{slug(name)} (DELETE #{endpoint})") if @debug
@@ -63,7 +190,12 @@ module Grafana
     end
 
     # Gets the home dashboard
-    # GET /api/dashboards/home
+    #
+    # @example
+    #    home_dashboard
+    #
+    # @return [Hash]
+    #
     def home_dashboard
 
       endpoint = '/api/dashboards/home'
@@ -74,7 +206,12 @@ module Grafana
     end
 
     # Tags for Dashboard
-    # GET /api/dashboards/tags
+    #
+    # @example
+    #    dashboard_tags
+    #
+    # @return [Hash]
+    #
     def dashboard_tags
 
       endpoint = '/api/dashboards/tags'
@@ -85,29 +222,30 @@ module Grafana
     end
 
     # Search Dashboards
-    # GET /api/search/
     #
-    #    searchDashboards( { :tags   => host } )
-    #    searchDashboards( { :tags   => [ host, 'tag1' ] } )
-    #    searchDashboards( { :tags   => [ 'tag2' ] } )
-    #    searchDashboards( { :query  => title } )
-    #    searchDashboards( { :starred => true } )
-    def search_dashboards( params = {} )
+    # @example
+    #    searchDashboards( tags: host )
+    #    searchDashboards( tags: [ host, 'tag1' ] )
+    #    searchDashboards( tags: [ 'tag2' ] )
+    #    searchDashboards( query: title )
+    #    searchDashboards( starred: true )
+    #
+    # @return [Hash]
+    #
+    def search_dashboards( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
 
-      query   = params.dig(:query)
-      starred = params.dig(:starred)
-      tags    = params.dig(:tags)
-      api     = []
+      query   = validate( params, required: false, var: 'query', type: String )
+      starred = validate( params, required: false, var: 'starred', type: Boolean )
+      tags    = validate( params, required: false, var: 'tags' )
 
-      api << format( 'query=%s', CGI.escape( query ) ) unless  query.nil?
+      api     = []
+      api << format( 'query=%s', CGI.escape( query ) ) unless( query.nil? )
       api << format( 'starred=%s', starred ? 'true' : 'false' ) unless( starred.nil? )
 
       unless( tags.nil? )
-
         tags = tags.join( '&tag=' ) if( tags.is_a?( Array ) )
-
         api << format( 'tag=%s', tags )
       end
 
@@ -120,7 +258,13 @@ module Grafana
       get( endpoint )
     end
 
-
+    # import Dashboards from directory
+    #
+    # @example
+    #    import_dashboards_from_directory( '/tmp/dashboards' )
+    #
+    # @return [Hash]
+    #
     def import_dashboards_from_directory( directory )
 
       raise ArgumentError.new('directory must be an String') unless( directory.is_a?(String) )
@@ -135,10 +279,9 @@ module Grafana
 
         dashboard = File.read( f )
         dashboard = JSON.parse( dashboard )
-        title     = dashboard.dig('dashboard','title') || f
 
         result[f.to_s] ||= {}
-        result[f.to_s] = create_dashboard( title: title, dashboard: dashboard )
+        result[f.to_s] = create_dashboard( dashboard: dashboard )
       end
 
       result