grafana 0.8.5 → 1.1.0

data/lib/grafana/network.rb

@@ -3,179 +3,208 @@ module Grafana
 
   module Network
 
+    # GET request
+    #
+    # @param endpoint [String]
+    #
     def get( endpoint )
-
       request( 'GET', endpoint )
     end
 
+    # POST request
+    #
+    # @param endpoint [String]
+    # @param data [Hash]
+    #
     def post( endpoint, data )
-
       request( 'POST', endpoint, data )
     end
 
+    # PUT request
+    #
+    # @param endpoint [String]
+    # @param data [Hash]
+    #
     def put( endpoint, data )
-
       request( 'PUT', endpoint, data )
     end
 
+    # PATCH request
+    #
+    # @param endpoint [String]
+    # @param data [Hash]
+    #
     def patch( endpoint, data )
-
       request( 'PATCH', endpoint, data )
     end
 
+    # DELETE request
+    #
+    # @param endpoint [String]
+    #
     def delete( endpoint )
-
       request( 'DELETE', endpoint )
     end
 
+
+    private
+    # helper function for all request methods
+    #
+    # @param method_type [String]
+    # @param endpoint [String]
+    # @param data [Hash]
+    #
+    # @example
+    #
+    #
+    # @return [Hash]
+    #
     def request( method_type = 'GET', endpoint = '/', data = {} )
 
-      raise 'try first login()' if  @api_instance.nil?
+      logger.debug( "request( method_type: #{method_type}, endpoint: #{endpoint}, data )" )
+
+      raise 'try first login()' if @api_instance.nil?
+
+#      login( username: @username, password: @password )
 
       response             = nil
       response_code        = 404
       response_body        = ''
 
       begin
-
         case method_type.upcase
         when 'GET'
-          response = @api_instance[endpoint].get( @headers )
+          response = @api_instance[endpoint].get( headers )
         when 'POST'
-          response = @api_instance[endpoint].post( data, @headers )
+          response = @api_instance[endpoint].post( data, headers )
         when 'PATCH'
-          response = @api_instance[endpoint].patch( data, @headers )
+          response = @api_instance[endpoint].patch( data, headers )
         when 'PUT'
-          # response = @api_instance[endpoint].put( data, @headers )
-          @api_instance[endpoint].put( data, @headers ) do |response, request, result|
 
-            case response.code
+          # response = @api_instance[endpoint].put( data, headers )
+          @api_instance[endpoint].put( data, headers ) do |resp, _request, _result|
+
+            response_code = resp.code.to_i
+            response_body = resp.body
+            response_body = JSON.parse(response_body) if response_body.is_a?(String)
+
+            #logger.debug( "code   : #{response_code}" )
+            #logger.debug( "message: #{response_body}" )
+
+            case response_code.to_i
             when 200
-              response_body = response.body
-              response_code = response.code.to_i
-              response_body = JSON.parse(response_body) if response_body.is_a?(String)
-
-              return {
-                'status' => response_code,
-                'message' => response_body.dig('message').nil? ? 'Successful' : response_body.dig('message')
-              }
+              return { 'status' => response_code, 'message' => response_body.dig('message').nil? ? 'Successful' : response_body.dig('message') }
             when 400
-              response_body = response.body
-              response_code = response.code.to_i
               raise RestClient::BadRequest
+            when 412
+              status  = response_body.dig('status')
+              message = response_body.dig('message')
+              message += " (#{status})"  unless(status.nil?)
+              return { 'status'  => response_code, 'message' => message }
+            when 422
+              logger.error('422')
+
+              response_body = response_body.first if(response_body.is_a?(Array))
+              # message_field_name = response_body.dig('fieldNames')
+
+              #status   = response_code # response_body.dig('status')
+              message  = response_body # .dig('message')
+              #message += " (#{status})"  unless(status.nil?)
+
+              # [{fieldNames"=>["Id"], "classification"=>"RequiredError", "message"=>"Required"}]
+
+              logger.error(message)
+              return { 'status'  => response_code, 'message' => message }
+#              #raise RestClient::UnprocessableEntity
             else
-#               logger.error( response.code )
-#               logger.error( response.body )
-
-              body = JSON.parse(response.body) if(response_body.is_a?(String))
-              return {
-                'status' => response_code,
-                'message' => body.dig('message')
-              }
+#              logger.error( response_code )
+#              logger.error( response_body )
+              return { 'status' => response_code, 'message' => response_body.dig('message') }
               # response.return! # (request, result)
             end
           end
 
         when 'DELETE'
-          response = @api_instance[endpoint].delete( @headers )
+
+          @api_instance[endpoint].delete( headers ) do |resp, _request, _result|
+
+            response_code = resp.code.to_i
+            response_body = resp.body
+            response_body = JSON.parse(response_body) if response_body.is_a?(String)
+
+            #logger.debug( "code   : #{response_code}" )
+            #logger.debug( "message: #{response_body}" )
+
+            case response_code.to_i
+            when 200
+              return { 'status' => response_code, 'message' => response_body.dig('message').nil? ? 'Successful' : response_body.dig('message') }
+            when 404
+              return { 'status' => response_code, 'message' => response_body.dig('message').nil? ? 'Successful' : response_body.dig('message') }
+            else
+#              logger.error( response_code )
+#              logger.error( response_body )
+              return { 'status' => response_code, 'message' => response_body.dig('message') }
+            end
+
+          end
+
         else
-          @logger.error( "Error: #{__method__} is not a valid request method." )
+          logger.error( "Error: #{__method__} is not a valid request method." )
           return false
         end
 
+#         logger.debug( "response: #{response} (#{response.class})" )
+
         response_code    = response.code.to_i
         response_body    = response.body
         response_headers = response.headers
 
-        if( @debug )
-          logger.debug("response_code : #{response_code}" )
-          logger.debug("response_body : #{response_body}" )
-          logger.debug("response_headers : #{response_headers}" )
-        end
-
         if( ( response_code >= 200 && response_code <= 299 ) || ( response_code >= 400 && response_code <= 499 ) )
 
-          result = JSON.parse( response_body )
-
-          if( result.is_a?(Array) )
-            r_result= {
-              'status' => response_code,
-              'message' => result
-            }
-            return r_result
+          if( response_body =~ /^\[.*\]$/ || response_body =~ /^\{.*\}$/ )
+            result = JSON.parse( response_body )
+            return { 'status' => response_code, 'message' => result } if( result.is_a?(Array) )
+          else
+            return { 'status' => response_code, 'message' => response_body }
           end
 
-          result_status = result.dig('status') if( result.is_a?( Hash ) )
-
+          result_status     = result.dig('status') if( result.is_a?( Hash ) )
           result['message'] = result_status unless( result_status.nil? )
           result['status']  = response_code
 
           return result
         else
-
-          @logger.error( "#{__method__} #{method_type.upcase} on #{endpoint} failed: HTTP #{response.code} - #{response_body}" )
-          @logger.error( @headers )
-          @logger.error( JSON.pretty_generate( response_headers ) )
+          logger.error( "#{__method__} #{method_type.upcase} on #{endpoint} failed: HTTP #{response.code} - #{response_body}" )
+          logger.error( headers )
+          logger.error( JSON.pretty_generate( response_headers ) )
 
           return JSON.parse( response_body )
         end
 
       rescue RestClient::BadRequest
-
         response_body = JSON.parse(response_body) if response_body.is_a?(String)
-
-        return {
-          'status' => 400,
-          'message' => response_body.dig('message').nil? ? 'Bad Request' : response_body.dig('message')
-        }
-
+        return { 'status' => 400, 'message' => response_body.dig('message').nil? ? 'Bad Request' : response_body.dig('message') }
       rescue RestClient::Unauthorized
-
-        return {
-          'status' => 401,
-          'message' => format('Not authorized to connect \'%s/%s\' - wrong username or password?', @url, endpoint)
-        }
+        return { 'status' => 401, 'message' => format('Not authorized to connect \'%s/%s\' - wrong username or password?', @url, endpoint) }
       rescue RestClient::Forbidden
-
-        return {
-          'status' => 403,
-          'message' => format('The operation is forbidden \'%s/%s\'', @url, endpoint)
-        }
-
+        return { 'status' => 403, 'message' => format('The operation is forbidden \'%s/%s\'', @url, endpoint) }
       rescue RestClient::NotFound
-
-        return {
-          'status' => 404,
-          'message' => 'Not Found'
-        }
-
+        return { 'status' => 404, 'message' => 'Not Found' }
       rescue RestClient::Conflict
-
-        return {
-          'status' => 409,
-          'message' => 'Conflict with the current state of the target resource'
-        }
-
+        return { 'status' => 409, 'message' => 'Conflict with the current state of the target resource' }
       rescue RestClient::PreconditionFailed
-
-        return {
-          'status' => 412,
-          'message' => 'Precondition failed. The Object probably already exists.'
-        }
-
-      rescue RestClient::ExceptionWithResponse => e
-
-        logger.error( "Error: #{__method__} #{method_type.upcase} on #{endpoint} error: '#{e}'" )
-        logger.error( data )
-        logger.error( @headers )
-        logger.error( JSON.pretty_generate( response_headers ) )
-
-        return false
-
+        return { 'status' => 412, 'message' => 'Precondition failed. The Object probably already exists.' }
+      rescue RestClient::PreconditionFailed
+        return { 'status' => 412, 'message' => 'Precondition failed. The Object probably already exists.' }
+      rescue RestClient::ExceptionWithResponse => error
+        #logger.error( "Error: (RestClient::ExceptionWithResponse) #{__method__} #{method_type.upcase} on #{endpoint} error: '#{error}'" )
+        #logger.error( "query: #{data}" )
+        return { 'status' => 500, 'message' => "Internal Server Error: #{error}" }
+      rescue => error
+        #logger.error( "Error: #{__method__} #{method_type.upcase} on #{endpoint} error: '#{error}'" )
+        #logger.error( "query: #{data}" )
+        return { 'status' => 500, 'message' => "Internal Server Error: #{error}" }
       end
-
     end
-
   end
-
 end

data/lib/grafana/organization.rb

@@ -103,7 +103,8 @@ module Grafana
 
       if( org.is_a?(Hash) && org.dig('status').to_i == 200 )
         org = org.dig('message')
-        return { 'status' => 404, 'message' => format('User \'%s\' are already in the organisation', login_or_email) } if( org.select { |x| x.dig('email') == login_or_email || x.dig('login') == login_or_email }.count >= 1 )
+        return { 'status' => 404, 'message' => format('User \'%s\' are already in the organisation', login_or_email) } \
+          if( org.select { |x| x.dig('email') == login_or_email || x.dig('login') == login_or_email }.count >= 1 )
       end
 
       endpoint = '/api/org/users'

data/lib/grafana/organizations.rb

@@ -23,11 +23,14 @@ module Grafana
     #
     def organization( organisation_id )
 
-      raise ArgumentError.new(format('wrong type. user \'organisation_id\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', organisation_id.class.to_s)) if( organisation_id.is_a?(String) && organisation_id.is_a?(Integer) )
+      if( organisation_id.is_a?(String) && organisation_id.is_a?(Integer))
+        raise ArgumentError.new(format('wrong type. \'organisation_id\' must be an String (for an Datasource name) ' \
+                                       'or an Integer (for an Datasource Id), given \'%s\'', organisation_id.class.to_s))
+      end
       raise ArgumentError.new('missing \'organisation_id\'') if( organisation_id.size.zero? )
 
       endpoint = format( '/api/orgs/%d', organisation_id ) if(organisation_id.is_a?(Integer))
-      endpoint = format( '/api/orgs/name/%s', URI.escape( organisation_id ) ) if(organisation_id.is_a?(String))
+      endpoint = format( '/api/orgs/name/%s', ERB::Util.url_encode( organisation_id ) ) if(organisation_id.is_a?(String))
 
       @logger.debug("Attempting to get existing data source Id #{organisation_id} (GET #{endpoint})") if  @debug
 
@@ -83,7 +86,10 @@ module Grafana
     #
     def organization_users( organization_id )
 
-      raise ArgumentError.new(format('wrong type. user \'organization_id\' must be an String (for an Organisation name) or an Integer (for an Organisation Id), given \'%s\'', organization_id.class.to_s)) if( organization_id.is_a?(String) && organization_id.is_a?(Integer) )
+      if( organization_id.is_a?(String) && organization_id.is_a?(Integer))
+        raise ArgumentError.new(format('wrong type. \'organization_id\' must be an String (for an Organisation name) '\
+                                       'or an Integer (for an Organisation Id), given \'%s\'', organization_id.class.to_s))
+      end
       raise ArgumentError.new('missing \'organization_id\'') if( organization_id.size.zero? )
 
       if(organization_id.is_a?(String))
@@ -266,7 +272,10 @@ module Grafana
     #
     def delete_organisation( organisation_id )
 
-      raise ArgumentError.new(format('wrong type. user \'organisation_id\' must be an String (for an Datasource name) or an Integer (for an Datasource Id), given \'%s\'', organisation_id.class.to_s)) if( organisation_id.is_a?(String) && organisation_id.is_a?(Integer) )
+      if( organisation_id.is_a?(String) && organisation_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'organisation_id\' must be an String (for an Organisation name) ' \
+                                       'or an Integer (for an Organisation Id), given \'%s\'', organisation_id.class.to_s))
+      end
       raise ArgumentError.new('missing \'organisation_id\'') if( organisation_id.size.zero? )
 
       if(organisation_id.is_a?(String))
@@ -275,7 +284,7 @@ module Grafana
         data.each do |d|
           organisation_map[d.dig('id')] = d.dig('name')
         end
-        organisation_id = organisation_map.select { |x,y| y == organisation_id }.keys.first if( organisation_map )
+        organisation_id = organisation_map.select { |_,y| y == organisation_id }.keys.first if( organisation_map )
       end
 
       return { 'status' => 404, 'message' => format( 'No Organisation \'%s\' found', organisation_id) } if( organisation_id.nil? )
@@ -308,7 +317,7 @@ module Grafana
       organization   = validate( params, required: true, var: 'organization', type: String )
       login_or_email = validate( params, required: true, var: 'login_or_email', type: String )
       role           = validate( params, required: true, var: 'role', type: String )
-      valid_roles    = ['Viewer', 'Editor', 'Read Only Editor', 'Admin']
+      valid_roles    = %w[Viewer Editor "Read Only Editor" Admin]
 
       # https://stackoverflow.com/questions/9333952/case-insensitive-arrayinclude?answertab=votes#tab-top
       # Do this once, or each time the array changes

data/lib/grafana/playlist.rb

@@ -0,0 +1,594 @@
+
+module Grafana
+
+  # +++
+  # title = "Playlist HTTP API "
+  # description = "Playlist Admin HTTP API"
+  # keywords = ["grafana", "http", "documentation", "api", "playlist"]
+  # aliases = ["/http_api/playlist/"]
+  # type = "docs"
+  # [menu.docs]
+  # name = "Playlist"
+  # parent = "http_api"
+  # +++
+
+  # https://github.com/grafana/grafana/blob/1165d098b0d0ae705955f9d2ea104beea98ca6eb/pkg/api/dtos/playlist.go
+
+  module Playlist
+
+    ## Playlist API
+    #
+    ### Search Playlist
+    #
+    #`GET /api/playlists`
+    #
+    #Get all existing playlist for the current organization using pagination
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #GET /api/playlists HTTP/1.1
+    #Accept: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #```
+    #
+    #  Querystring Parameters:
+    #
+    #  These parameters are used as querystring parameters.
+    #
+    #  - **query** - Limit response to playlist having a name like this value.
+    #  - **limit** - Limit response to *X* number of playlist.
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #[
+    #  {
+    #    "id": 1,
+    #    "name": "my playlist",
+    #    "interval": "5m"
+    #  }
+    #]
+    #```
+    def playlists
+
+      endpoint = '/api/playlists'
+
+      @logger.debug("Attempting to get all existing playlists (GET #{endpoint})") if @debug
+
+      playlists = get( endpoint )
+
+      return { 'status' => 404, 'message' => 'No Playlists found' } if( playlists.nil? || playlists == false || playlists.dig('status').to_i != 200 )
+
+      playlists
+    end
+
+    ### Get one playlist
+    #
+    #`GET /api/playlists/:id`
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #GET /api/playlists/1 HTTP/1.1
+    #Accept: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #```
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #{
+    #  "id" : 1,
+    #  "name": "my playlist",
+    #  "interval": "5m",
+    #  "orgId": "my org",
+    #  "items": [
+    #    {
+    #      "id": 1,
+    #      "playlistId": 1,
+    #      "type": "dashboard_by_id",
+    #      "value": "3",
+    #      "order": 1,
+    #      "title":"my third dasboard"
+    #    },
+    #    {
+    #      "id": 2,
+    #      "playlistId": 1,
+    #      "type": "dashboard_by_tag",
+    #      "value": "myTag",
+    #      "order": 2,
+    #      "title":"my other dasboard"
+    #    }
+    #  ]
+    #}
+    #```
+
+    def playlist( playlist_id )
+
+      if( playlist_id.is_a?(String) && playlist_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'playlist_id\' must be an String (for an Playlist name) or an Integer (for an Playlist Id), given \'%s\'', playlist_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'playlist_id\'') if( playlist_id.size.zero? )
+
+      if(playlist_id.is_a?(String))
+
+        data = playlists
+        status = data.dig('status')
+        d = data.dig('message')
+        data = d.select { |k| k['name'] == playlist_id }
+
+        return { 'status' => 404, 'message' => format( 'No Playlist \'%s\' found', playlist_id) } if( data.size.zero? )
+
+        unless( data.empty? )
+          playlist_data = []
+          data.each_entry do |k|
+            playlist_data << playlist( k['id'] )
+          end
+
+          return { 'status' => status, 'playlists' => playlist_data }
+        end
+      end
+
+      raise format('playlist id can not be 0') if( playlist_id.zero? )
+
+      endpoint = format('/api/playlists/%d', playlist_id )
+
+      @logger.debug("Attempting to get existing playlist id #{playlist_id} (GET #{endpoint})") if  @debug
+
+      result = get(endpoint)
+
+      return { 'status' => 404, 'message' => 'playlist is empty', 'items' => [] } if( result.dig('status') == 404 )
+
+      result
+    end
+
+    ### Get Playlist items
+
+    #`GET /api/playlists/:id/items`
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #GET /api/playlists/1/items HTTP/1.1
+    #Accept: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #```
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #[
+    #  {
+    #    "id": 1,
+    #    "playlistId": 1,
+    #    "type": "dashboard_by_id",
+    #    "value": "3",
+    #    "order": 1,
+    #    "title":"my third dasboard"
+    #  },
+    #  {
+    #    "id": 2,
+    #    "playlistId": 1,
+    #    "type": "dashboard_by_tag",
+    #    "value": "myTag",
+    #    "order": 2,
+    #    "title":"my other dasboard"
+    #  }
+    #]
+    #```
+
+    def playlist_items( playlist_id, multi_result = false )
+
+      if( playlist_id.is_a?(String) && playlist_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'playlist_id\' must be an String (for an playlist name) or an Integer (for an playlist Id), given \'%s\'', playlist_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'playlist_id\'') if( playlist_id.size.zero? )
+
+      tmp_playlists = playlists
+
+      begin
+        status  = tmp_playlists.dig('status').to_i
+        message = tmp_playlists.dig('message')
+
+        return tmp_playlists if( status != 200 )
+
+        data = message.select { |k| k['id'] == playlist_id } if( playlist_id.is_a?(Integer) )
+        data = message.select { |k| k['name'] == playlist_id } if( playlist_id.is_a?(String) )
+
+        return { 'status' => 404, 'message' => 'No Playlist found' } if( !data.is_a?(Array) || data.count.zero? || status.to_i != 200 )
+        return { 'status' => 404, 'message' => format('found %d playlists with name %s', data.count, playlist_id ) } if( data.count > 1 && multi_result == false )
+
+        id = data.first.dig('id')
+
+      rescue
+        return { 'status' => 404, 'message' => 'No Playlists found' } if( playlists.nil? || playlists == false || playlists.dig('status').to_i != 200 )
+      end
+
+      endpoint = "/api/playlists/#{id}/items"
+
+      result = get( endpoint )
+
+      return { 'status' => 404, 'message' => 'playlist is empty' } if( result.dig('status') == 404 )
+
+      result
+    end
+
+    ### Get Playlist dashboards
+    #
+    #`GET /api/playlists/:id/dashboards`
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #GET /api/playlists/1/dashboards HTTP/1.1
+    #Accept: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #```
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #[
+    #  {
+    #    "id": 3,
+    #    "title": "my third dasboard",
+    #    "order": 1,
+    #  },
+    #  {
+    #    "id": 5,
+    #    "title":"my other dasboard"
+    #    "order": 2,
+    #
+    #  }
+    #]
+    #```
+
+    def playlist_dashboards( playlist_id )
+
+      raise ArgumentError.new(format('wrong type. \'playlist_id\' must be an Integer, given \'%s\'', playlist_id.class)) unless( playlist_id.is_a?(Integer) )
+      raise ArgumentError.new('missing \'playlist_id\'') if( playlist_id.size.zero? )
+
+      endpoint = format('/api/playlists/%s/dashboards', playlist_id)
+
+      @logger.debug( "Attempting to get playlist (GET #{endpoint})" ) if @debug
+      get(endpoint)
+    end
+
+    # Create a playlist
+
+    # `POST /api/playlists/`
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #PUT /api/playlists/1 HTTP/1.1
+    #Accept: application/json
+    #Content-Type: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #  {
+    #    "name": "my playlist",
+    #    "interval": "5m",
+    #    "items": [
+    #      {
+    #        "type": "dashboard_by_id",
+    #        "value": "3",
+    #        "order": 1,
+    #        "title":"my third dasboard"
+    #      },
+    #      {
+    #        "type": "dashboard_by_tag",
+    #        "value": "myTag",
+    #        "order": 2,
+    #        "title":"my other dasboard"
+    #      }
+    #    ]
+    #  }
+    #```
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #  {
+    #    "id": 1,
+    #    "name": "my playlist",
+    #    "interval": "5m"
+    #  }
+    #```
+
+    def create_playlist( 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? )
+
+#      v, mv = version.values
+#      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      name     = validate( params, required: true , var: 'name'      , type: String )
+      interval = validate( params, required: true , var: 'interval'  , type: String )
+      items    = validate( params, required: true , var: 'items'     , type: Array )
+
+      return { 'status' => 404, 'message' => 'There are no elements for a playlist' } if(items.count.zero?)
+
+      payload_items = create_playlist_items(items)
+
+      payload = {
+        name:     name,
+        interval: interval,
+        items:    payload_items
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      endpoint = '/api/playlists'
+
+      post(endpoint, payload.to_json)
+    end
+
+    ### Update a playlist
+    #
+    #`PUT /api/playlists/:id`
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #PUT /api/playlists/1 HTTP/1.1
+    #Accept: application/json
+    #Content-Type: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #  {
+    #    "name": "my playlist",
+    #    "interval": "5m",
+    #    "items": [
+    #      {
+    #        "playlistId": 1,
+    #        "type": "dashboard_by_id",
+    #        "value": "3",
+    #        "order": 1,
+    #        "title":"my third dasboard"
+    #      },
+    #      {
+    #        "playlistId": 1,
+    #        "type": "dashboard_by_tag",
+    #        "value": "myTag",
+    #        "order": 2,
+    #        "title":"my other dasboard"
+    #      }
+    #    ]
+    #  }
+    #```
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #{
+    #  "id" : 1,
+    #  "name": "my playlist",
+    #  "interval": "5m",
+    #  "orgId": "my org",
+    #  "items": [
+    #    {
+    #      "id": 1,
+    #      "playlistId": 1,
+    #      "type": "dashboard_by_id",
+    #      "value": "3",
+    #      "order": 1,
+    #      "title":"my third dasboard"
+    #    },
+    #    {
+    #      "id": 2,
+    #      "playlistId": 1,
+    #      "type": "dashboard_by_tag",
+    #      "value": "myTag",
+    #      "order": 2,
+    #      "title":"my other dasboard"
+    #    }
+    #  ]
+    #}
+    #```
+
+    def update_playlist( 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? )
+
+      playlist_id   = validate( params, required: true , var: 'playlist' )
+      name          = validate( params, required: false, var: 'name' )
+      interval      = validate( params, required: false, var: 'interval', type: String )
+      # organisation = validate( params, required: false, var: 'organisation' )
+      items         = validate( params, required: false, var: 'items', type: Array )
+
+      tmp_playlists    = playlists
+
+      data = []
+
+      begin
+        status  = tmp_playlists.dig('status').to_i
+        message = tmp_playlists.dig('message')
+
+        return tmp_playlists if( status != 200 )
+
+        data = message.select { |k| k['id'] == playlist_id } if( playlist_id.is_a?(Integer) )
+        data = message.select { |k| k['name'] == playlist_id } if( playlist_id.is_a?(String) )
+
+        return { 'status' => 404, 'message' => 'no playlist found' } if( !data.is_a?(Array) || data.count.zero? || status.to_i != 200 )
+        return { 'status' => 404, 'message' => format('found %d playlists with name %s', data.count, playlist_id ) } if( data.count > 1 && multi_result == false )
+
+      rescue
+        return { 'status' => 404, 'message' => 'no playlists found' } if( playlists.nil? || playlists == false || playlists.dig('status').to_i != 200 )
+      end
+
+      playlist_id   = data.first.dig('id')
+      # playlist_name = data.first.dig('name')
+      payload_items = create_playlist_items(items, playlist_id)
+
+      payload = {
+        id:       playlist_id,
+        name:     name,
+        interval: interval,
+        items:    payload_items
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      endpoint = format( '/api/playlists/%d', playlist_id )
+
+      put( endpoint, payload.to_json )
+
+    end
+
+
+    ### Delete a playlist
+    #
+    #`DELETE /api/playlists/:id`
+    #
+    #**Example Request**:
+    #
+    #```bash
+    #DELETE /api/playlists/1 HTTP/1.1
+    #Accept: application/json
+    #Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+    #```
+    #
+    #**Example Response**:
+    #
+    #```json
+    #HTTP/1.1 200
+    #Content-Type: application/json
+    #{}
+    #```
+
+    def delete_playlist(playlist_id, multi_result = false )
+
+      if( playlist_id.is_a?(String) && playlist_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'playlist_id\' must be an String (for an Playlist name) or an Integer (for an Playlist Id), given \'%s\'', playlist_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'playlist_id\'') if( playlist_id.size.zero? )
+
+      tmp_playlists = playlists
+
+      data = []
+
+      begin
+        status  = tmp_playlists.dig('status').to_i
+        message = tmp_playlists.dig('message')
+
+        return tmp_playlists if( status != 200 )
+
+        data = message.select { |k| k['id'] == playlist_id } if( playlist_id.is_a?(Integer) )
+        data = message.select { |k| k['name'] == playlist_id } if( playlist_id.is_a?(String) )
+
+        return { 'status' => 404, 'message' => 'no playlist found' } if( !data.is_a?(Array) || data.count.zero? || status.to_i != 200 )
+        return { 'status' => 404, 'message' => format('found %d playlists with name %s', data.count, playlist_id ) } if( data.count > 1 && multi_result == false )
+
+      rescue
+        return { 'status' => 404, 'message' => 'no playlists found' } if( playlists.nil? || playlists == false || playlists.dig('status').to_i != 200 )
+      end
+
+      if( multi_result == true )
+
+        result = { 'status' => 0, 'message' => 'under development' }
+        data.each do |x|
+
+          endpoint = format( '/api/playlists/%d', x.dig('id') )
+
+          begin
+            result = delete( endpoint )
+          rescue => error
+            logger.error( "error: #{error}" )
+          end
+        end
+
+        # return result
+      else
+
+        playlist_id = data.first.dig('id')
+
+        endpoint = format( '/api/playlists/%d', playlist_id )
+
+        result = delete( endpoint )
+
+        if(result.dig('status').to_i == 500)
+          # check if the playlist exists
+          r = playlist( playlist_id )
+          return { 'status' => 200, 'message' => 'playlist deleted' } if(r.dig('status').to_i == 404)
+        end
+
+        # return result
+      end
+
+      result
+    end
+
+
+    private
+    def create_playlist_items( items, playlist_id = nil)
+
+      playlist_items   = []
+
+      items.each do |r|
+        playlist_element = {}
+
+        if( r['name'] )
+
+          playlist_name = search_dashboards( query: r['name'] )
+          playlist_name_status = playlist_name.dig('status')
+
+          next unless( playlist_name_status == 200 )
+
+          playlist_name       = playlist_name.dig('message')
+          playlist_name_id    = playlist_name.first.dig('id')
+          playlist_name_title = playlist_name.first.dig('title')
+
+          playlist_element[:type]  = 'dashboard_by_id'
+          playlist_element[:value] = playlist_name_id.to_s
+          playlist_element[:title] = playlist_name_title
+          playlist_element[:playlistId] = playlist_id unless(playlist_id.nil?)
+
+        elsif( r['id'] )
+
+          uid = dashboard_by_uid(r['id'])
+          uid_status = uid.dig('status')
+
+          next unless( uid_status == 200 )
+
+          playlist_element[:type]  = 'dashboard_by_id'
+          playlist_element[:value] = r['id']
+          playlist_element[:playlistId] = playlist_id unless(playlist_id.nil?)
+
+        elsif( r['tag'] )
+
+          tags        = search_dashboards( tags: r['tag'] )
+          tags_status = tags.dig('status')
+
+          next unless( tags_status == 200 )
+
+          playlist_element[:type]  = 'dashboard_by_tag'
+          playlist_element[:value] = r['tag']
+          playlist_element[:title] = r['tag']
+          playlist_element[:playlistId] = playlist_id unless(playlist_id.nil?)
+
+        else
+          next
+        end
+
+        playlist_element[:order] = r['order'] if(r['order'])
+
+        playlist_items << playlist_element if(playlist_element.count >= 4)
+      end
+
+      playlist_items
+    end
+
+  end
+end