Merge remote-tracking branch 'upstream/master' into 19737-read-only-auditor19737-read-only-auditor

* upstream/master: (1277 commits)
  Grapify the labels API
  Fix typo in project settings that prevents users from enabling container registry.
  Fix old monitoring links to point to the new location
  Added path parameter to Commits API
  fixes build with cache:clear issue
  Merge branch 'security-fix-leaking-namespace-name' into 'security'
  Fix authored vote from notes
  Grapify builds API
  Add changelog item for groups 404 on relative url
  Add relative url support to routing contrainers
  Update project member controller to match recent master logic
  Add parentheses around return redirect_to method
  Trigger change even in select2 test helper to produce production-like behaviour
  Refactor js that disable form submit if no members selected
  Improve create project member test at project_members_controller_spec
  Move changelog item to 8.14
  Refactor create member tests from group_members_controller_spec
  Refactor groups/projects members controller
  Gracefully handle adding of no users to projects and groups
  Revert "Change "Group#web_url" to return "/groups/twitter" rather than "/twitter"."
  ...

25 files changed, 846 insertions, 666 deletions

diff --git a/lib/api/access_requests.rb b/lib/api/access_requests.rb
index 9d1d9058996..87915b19480 100644
--- a/lib/api/access_requests.rb
+++ b/lib/api/access_requests.rb
@@ -5,32 +5,27 @@ module API
     helpers ::API::Helpers::MembersHelpers
 
     %w[group project].each do |source_type|
+      params do
+        requires :id, type: String, desc: "The #{source_type} ID"
+      end
       resource source_type.pluralize do
-        # Get a list of group/project access requests viewable by the authenticated user.
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #
-        # Example Request:
-        #  GET /groups/:id/access_requests
-        #  GET /projects/:id/access_requests
+        desc "Gets a list of access requests for a #{source_type}." do
+          detail 'This feature was introduced in GitLab 8.11.'
+          success Entities::AccessRequester
+        end
         get ":id/access_requests" do
           source = find_source(source_type, params[:id])
-          authorize_admin_source!(source_type, source)
 
-          access_requesters = paginate(source.requesters.includes(:user))
+          access_requesters = AccessRequestsFinder.new(source).execute!(current_user)
+          access_requesters = paginate(access_requesters.includes(:user))
 
           present access_requesters.map(&:user), with: Entities::AccessRequester, source: source
         end
 
-        # Request access to the group/project
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #
-        # Example Request:
-        #  POST /groups/:id/access_requests
-        #  POST /projects/:id/access_requests
+        desc "Requests access for the authenticated user to a #{source_type}." do
+          detail 'This feature was introduced in GitLab 8.11.'
+          success Entities::AccessRequester
+        end
         post ":id/access_requests" do
           source = find_source(source_type, params[:id])
           access_requester = source.request_access(current_user)
@@ -42,42 +37,34 @@ module API
           end
         end
 
-        # Approve a group/project access request
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   user_id (required) - The user ID of the access requester
-        #   access_level (optional) - Access level
-        #
-        # Example Request:
-        #   PUT /groups/:id/access_requests/:user_id/approve
-        #   PUT /projects/:id/access_requests/:user_id/approve
+        desc 'Approves an access request for the given user.' do
+          detail 'This feature was introduced in GitLab 8.11.'
+          success Entities::Member
+        end
+        params do
+          requires :user_id, type: Integer, desc: 'The user ID of the access requester'
+          optional :access_level, type: Integer, desc: 'A valid access level (defaults: `30`, developer access level)'
+        end
         put ':id/access_requests/:user_id/approve' do
-          required_attributes! [:user_id]
           source = find_source(source_type, params[:id])
 
-          member = ::Members::ApproveAccessRequestService.new(source, current_user, params).execute
+          member = ::Members::ApproveAccessRequestService.new(source, current_user, declared(params)).execute
 
           status :created
           present member.user, with: Entities::Member, member: member
         end
 
-        # Deny a group/project access request
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   user_id (required) - The user ID of the access requester
-        #
-        # Example Request:
-        #   DELETE /groups/:id/access_requests/:user_id
-        #   DELETE /projects/:id/access_requests/:user_id
+        desc 'Denies an access request for the given user.' do
+          detail 'This feature was introduced in GitLab 8.11.'
+        end
+        params do
+          requires :user_id, type: Integer, desc: 'The user ID of the access requester'
+        end
         delete ":id/access_requests/:user_id" do
-          required_attributes! [:user_id]
           source = find_source(source_type, params[:id])
 
-          access_requester = source.requesters.find_by!(user_id: params[:user_id])
-
-          ::Members::DestroyService.new(access_requester, current_user).execute
+          ::Members::DestroyService.new(source, current_user, params).
+            execute(:requesters)
         end
       end
     end
diff --git a/lib/api/api.rb b/lib/api/api.rb
index cb47ec8f33f..67109ceeef9 100644
--- a/lib/api/api.rb
+++ b/lib/api/api.rb
@@ -31,11 +31,12 @@ module API
     # Keep in alphabetical order
     mount ::API::AccessRequests
     mount ::API::AwardEmoji
+    mount ::API::Boards
     mount ::API::Branches
     mount ::API::BroadcastMessages
     mount ::API::Builds
-    mount ::API::CommitStatuses
     mount ::API::Commits
+    mount ::API::CommitStatuses
     mount ::API::DeployKeys
     mount ::API::Deployments
     mount ::API::Environments
@@ -45,19 +46,18 @@ module API
     mount ::API::Issues
     mount ::API::Keys
     mount ::API::Labels
-    mount ::API::LicenseTemplates
     mount ::API::Lint
     mount ::API::Members
-    mount ::API::MergeRequests
     mount ::API::MergeRequestDiffs
+    mount ::API::MergeRequests
     mount ::API::Milestones
     mount ::API::Namespaces
     mount ::API::Notes
     mount ::API::NotificationSettings
     mount ::API::Pipelines
     mount ::API::ProjectHooks
-    mount ::API::ProjectSnippets
     mount ::API::Projects
+    mount ::API::ProjectSnippets
     mount ::API::Repositories
     mount ::API::Runners
     mount ::API::Services
@@ -72,5 +72,10 @@ module API
     mount ::API::Triggers
     mount ::API::Users
     mount ::API::Variables
+    mount ::API::Version
+
+    route :any, '*path' do
+      error!('404 Not Found', 404)
+    end
   end
 end
diff --git a/lib/api/award_emoji.rb b/lib/api/award_emoji.rb
index 2461a783ea8..e9ccba3b465 100644
--- a/lib/api/award_emoji.rb
+++ b/lib/api/award_emoji.rb
@@ -8,16 +8,19 @@ module API
         awardable_string = awardable_type.pluralize
         awardable_id_string = "#{awardable_type}_id"
 
+        params do
+          requires :id, type: String, desc: 'The ID of a project'
+          requires :"#{awardable_id_string}", type: Integer, desc: "The ID of an Issue, Merge Request or Snippet"
+        end
+
         [ ":id/#{awardable_string}/:#{awardable_id_string}/award_emoji",
           ":id/#{awardable_string}/:#{awardable_id_string}/notes/:note_id/award_emoji"
         ].each do |endpoint|
-          # Get a list of project +awardable+ award emoji
-          #
-          # Parameters:
-          #   id (required)           - The ID of a project
-          #   awardable_id (required) - The ID of an issue or MR
-          # Example Request:
-          #   GET /projects/:id/issues/:awardable_id/award_emoji
+
+          desc 'Get a list of project +awardable+ award emoji' do
+            detail 'This feature was introduced in 8.9'
+            success Entities::AwardEmoji
+          end
           get endpoint do
             if can_read_awardable?
               awards = paginate(awardable.award_emoji)
@@ -27,14 +30,13 @@ module API
             end
           end
 
-          # Get a specific award emoji
-          #
-          # Parameters:
-          #   id (required)           - The ID of a project
-          #   awardable_id (required) - The ID of an issue or MR
-          #   award_id (required)     - The ID of the award
-          # Example Request:
-          #   GET /projects/:id/issues/:awardable_id/award_emoji/:award_id
+          desc 'Get a specific award emoji' do
+            detail 'This feature was introduced in 8.9'
+            success Entities::AwardEmoji
+          end
+          params do
+            requires :award_id, type: Integer, desc: 'The ID of the award'
+          end
           get "#{endpoint}/:award_id" do
             if can_read_awardable?
               present awardable.award_emoji.find(params[:award_id]), with: Entities::AwardEmoji
@@ -43,17 +45,14 @@ module API
             end
           end
 
-          # Award a new Emoji
-          #
-          # Parameters:
-          #   id (required) - The ID of a project
-          #   awardable_id (required) - The ID of an issue or mr
-          #   name (required) - The name of a award_emoji (without colons)
-          # Example Request:
-          #   POST /projects/:id/issues/:awardable_id/award_emoji
+          desc 'Award a new Emoji' do
+            detail 'This feature was introduced in 8.9'
+            success Entities::AwardEmoji
+          end
+          params do
+            requires :name, type: String, desc: 'The name of a award_emoji (without colons)'
+          end
           post endpoint do
-            required_attributes! [:name]
-
             not_found!('Award Emoji') unless can_read_awardable? && can_award_awardable?
 
             award = awardable.create_award_emoji(params[:name], current_user)
@@ -65,14 +64,13 @@ module API
             end
           end
 
-          # Delete a +awardables+ award emoji
-          #
-          # Parameters:
-          #   id (required) - The ID of a project
-          #   awardable_id (required) - The ID of an issue or MR
-          #   award_emoji_id (required) - The ID of an award emoji
-          # Example Request:
-          #   DELETE /projects/:id/issues/:issue_id/notes/:note_id/award_emoji/:award_id
+          desc 'Delete a +awardables+ award emoji' do
+            detail 'This feature was introduced in 8.9'
+            success Entities::AwardEmoji
+          end
+          params do
+            requires :award_id, type: Integer, desc: 'The ID of an award emoji'
+          end
           delete "#{endpoint}/:award_id" do
             award = awardable.award_emoji.find(params[:award_id])
 
diff --git a/lib/api/boards.rb b/lib/api/boards.rb
new file mode 100644
index 00000000000..4ac491edc1b
--- /dev/null
+++ b/lib/api/boards.rb
@@ -0,0 +1,132 @@
+module API
+  # Boards API
+  class Boards < Grape::API
+    before { authenticate! }
+
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
+    resource :projects do
+      desc 'Get all project boards' do
+        detail 'This feature was introduced in 8.13'
+        success Entities::Board
+      end
+      get ':id/boards' do
+        authorize!(:read_board, user_project)
+        present user_project.boards, with: Entities::Board
+      end
+
+      params do
+        requires :board_id, type: Integer, desc: 'The ID of a board'
+      end
+      segment ':id/boards/:board_id' do
+        helpers do
+          def project_board
+            board = user_project.boards.first
+
+            if params[:board_id] == board.id
+              board
+            else
+              not_found!('Board')
+            end
+          end
+
+          def board_lists
+            project_board.lists.destroyable
+          end
+        end
+
+        desc 'Get the lists of a project board' do
+          detail 'Does not include `backlog` and `done` lists. This feature was introduced in 8.13'
+          success Entities::List
+        end
+        get '/lists' do
+          authorize!(:read_board, user_project)
+          present board_lists, with: Entities::List
+        end
+
+        desc 'Get a list of a project board' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :list_id, type: Integer, desc: 'The ID of a list'
+        end
+        get '/lists/:list_id' do
+          authorize!(:read_board, user_project)
+          present board_lists.find(params[:list_id]), with: Entities::List
+        end
+
+        desc 'Create a new board list' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :label_id, type: Integer, desc: 'The ID of an existing label'
+        end
+        post '/lists' do
+          unless available_labels.exists?(params[:label_id])
+            render_api_error!({ error: 'Label not found!' }, 400)
+          end
+
+          authorize!(:admin_list, user_project)
+
+          service = ::Boards::Lists::CreateService.new(user_project, current_user,
+            { label_id: params[:label_id] })
+
+          list = service.execute(project_board)
+
+          if list.valid?
+            present list, with: Entities::List
+          else
+            render_validation_error!(list)
+          end
+        end
+
+        desc 'Moves a board list to a new position' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :list_id,  type: Integer, desc: 'The ID of a list'
+          requires :position, type: Integer, desc: 'The position of the list'
+        end
+        put '/lists/:list_id' do
+          list = project_board.lists.movable.find(params[:list_id])
+
+          authorize!(:admin_list, user_project)
+
+          service = ::Boards::Lists::MoveService.new(user_project, current_user,
+              { position: params[:position] })
+
+          if service.execute(list)
+            present list, with: Entities::List
+          else
+            render_api_error!({ error: "List could not be moved!" }, 400)
+          end
+        end
+
+        desc 'Delete a board list' do
+          detail 'This feature was introduced in 8.13'
+          success Entities::List
+        end
+        params do
+          requires :list_id, type: Integer, desc: 'The ID of a board list'
+        end
+        delete "/lists/:list_id" do
+          authorize!(:admin_list, user_project)
+
+          list = board_lists.find(params[:list_id])
+
+          service = ::Boards::Lists::DestroyService.new(user_project, current_user)
+
+          if service.execute(list)
+            present list, with: Entities::List
+          else
+            render_api_error!({ error: 'List could not be deleted!' }, 400)
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/api/branches.rb b/lib/api/branches.rb
index b615703df93..6d827448994 100644
--- a/lib/api/branches.rb
+++ b/lib/api/branches.rb
@@ -54,43 +54,25 @@ module API
         not_found!('Branch') unless @branch
         protected_branch = user_project.protected_branches.find_by(name: @branch.name)
 
-        developers_can_merge = to_boolean(params[:developers_can_merge])
-        developers_can_push = to_boolean(params[:developers_can_push])
-
         protected_branch_params = {
-          name: @branch.name
+          name: @branch.name,
+          developers_can_push: to_boolean(params[:developers_can_push]),
+          developers_can_merge: to_boolean(params[:developers_can_merge])
         }
 
-        # If `developers_can_merge` is switched off, _all_ `DEVELOPER`
-        # merge_access_levels need to be deleted.
-        if developers_can_merge == false
-          protected_branch.merge_access_levels.where(access_level: Gitlab::Access::DEVELOPER).destroy_all
-        end
+        service_args = [user_project, current_user, protected_branch_params]
 
-        # If `developers_can_push` is switched off, _all_ `DEVELOPER`
-        # push_access_levels need to be deleted.
-        if developers_can_push == false
-          protected_branch.push_access_levels.where(access_level: Gitlab::Access::DEVELOPER).destroy_all
-        end
+        protected_branch = if protected_branch
+                             ProtectedBranches::ApiUpdateService.new(*service_args).execute(protected_branch)
+                           else
+                             ProtectedBranches::ApiCreateService.new(*service_args).execute
+                           end
 
-        protected_branch_params.merge!(
-          merge_access_levels_attributes: [{
-            access_level: developers_can_merge ? Gitlab::Access::DEVELOPER : Gitlab::Access::MASTER
-          }],
-          push_access_levels_attributes: [{
-            access_level: developers_can_push ? Gitlab::Access::DEVELOPER : Gitlab::Access::MASTER
-          }]
-        )
-
-        if protected_branch
-          service = ProtectedBranches::UpdateService.new(user_project, current_user, protected_branch_params)
-          service.execute(protected_branch)
+        if protected_branch.valid?
+          present @branch, with: Entities::RepoBranch, project: user_project
         else
-          service = ProtectedBranches::CreateService.new(user_project, current_user, protected_branch_params)
-          service.execute
+          render_api_error!(protected_branch.errors.full_messages, 422)
         end
-
-        present @branch, with: Entities::RepoBranch, project: user_project
       end
 
       # Unprotect a single branch
@@ -123,7 +105,7 @@ module API
       post ":id/repository/branches" do
         authorize_push_project
         result = CreateBranchService.new(user_project, current_user).
-          execute(params[:branch_name], params[:ref])
+                 execute(params[:branch_name], params[:ref])
 
         if result[:status] == :success
           present result[:branch],
@@ -142,10 +124,10 @@ module API
       # Example Request:
       #   DELETE /projects/:id/repository/branches/:branch
       delete ":id/repository/branches/:branch",
-          requirements: { branch: /.+/ } do
+             requirements: { branch: /.+/ } do
         authorize_push_project
         result = DeleteBranchService.new(user_project, current_user).
-          execute(params[:branch])
+                 execute(params[:branch])
 
         if result[:status] == :success
           {
diff --git a/lib/api/builds.rb b/lib/api/builds.rb
index 52bdbcae5a8..67adca6605f 100644
--- a/lib/api/builds.rb
+++ b/lib/api/builds.rb
@@ -3,15 +3,32 @@ module API
   class Builds < Grape::API
     before { authenticate! }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
-      # Get a project builds
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   scope (optional) - The scope of builds to show (one or array of: pending, running, failed, success, canceled;
-      #                      if none provided showing all builds)
-      # Example Request:
-      #   GET /projects/:id/builds
+      helpers do
+        params :optional_scope do
+          optional :scope, types: [String, Array[String]], desc: 'The scope of builds to show',
+                           values:  ['pending', 'running', 'failed', 'success', 'canceled'],
+                           coerce_with: ->(scope) {
+                             if scope.is_a?(String)
+                               [scope]
+                             elsif scope.is_a?(Hashie::Mash)
+                               scope.values
+                             else
+                               ['unknown']
+                             end
+                           }
+        end
+      end
+
+      desc 'Get a project builds' do
+        success Entities::Build
+      end
+      params do
+        use :optional_scope
+      end
       get ':id/builds' do
         builds = user_project.builds.order('id DESC')
         builds = filter_builds(builds, params[:scope])
@@ -20,15 +37,13 @@ module API
                                   user_can_download_artifacts: can?(current_user, :read_build, user_project)
       end
 
-      # Get builds for a specific commit of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The SHA id of a commit
-      #   scope (optional) - The scope of builds to show (one or array of: pending, running, failed, success, canceled;
-      #                      if none provided showing all builds)
-      # Example Request:
-      #   GET /projects/:id/repository/commits/:sha/builds
+      desc 'Get builds for a specific commit of a project' do
+        success Entities::Build
+      end
+      params do
+        requires :sha,   type: String, desc: 'The SHA id of a commit'
+        use :optional_scope
+      end
       get ':id/repository/commits/:sha/builds' do
         authorize_read_builds!
 
@@ -42,13 +57,12 @@ module API
                                   user_can_download_artifacts: can?(current_user, :read_build, user_project)
       end
 
-      # Get a specific build of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   build_id (required) - The ID of a build
-      # Example Request:
-      #   GET /projects/:id/builds/:build_id
+      desc 'Get a specific build of a project' do
+        success Entities::Build
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       get ':id/builds/:build_id' do
         authorize_read_builds!
 
@@ -58,13 +72,12 @@ module API
                        user_can_download_artifacts: can?(current_user, :read_build, user_project)
       end
 
-      # Download the artifacts file from build
-      #
-      # Parameters:
-      #   id (required) - The ID of a build
-      #   token (required) - The build authorization token
-      # Example Request:
-      #   GET /projects/:id/builds/:build_id/artifacts
+      desc 'Download the artifacts file from build' do
+        detail 'This feature was introduced in GitLab 8.5'
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       get ':id/builds/:build_id/artifacts' do
         authorize_read_builds!
 
@@ -73,14 +86,13 @@ module API
         present_artifacts!(build.artifacts_file)
       end
 
-      # Download the artifacts file from ref_name and job
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   ref_name (required) - The ref from repository
-      #   job (required) - The name for the build
-      # Example Request:
-      #   GET /projects/:id/builds/artifacts/:ref_name/download?job=name
+      desc 'Download the artifacts file from build' do
+        detail 'This feature was introduced in GitLab 8.10'
+      end
+      params do
+        requires :ref_name, type: String, desc: 'The ref from repository'
+        requires :job,      type: String, desc: 'The name for the build'
+      end
       get ':id/builds/artifacts/:ref_name/download',
         requirements: { ref_name: /.+/ } do
         authorize_read_builds!
@@ -91,17 +103,13 @@ module API
         present_artifacts!(latest_build.artifacts_file)
       end
 
-      # Get a trace of a specific build of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   build_id (required) - The ID of a build
-      # Example Request:
-      #   GET /projects/:id/build/:build_id/trace
-      #
       # TODO: We should use `present_file!` and leave this implementation for backward compatibility (when build trace
       #       is saved in the DB instead of file). But before that, we need to consider how to replace the value of
       #       `runners_token` with some mask (like `xxxxxx`) when sending trace file directly by workhorse.
+      desc 'Get a trace of a specific build of a project'
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       get ':id/builds/:build_id/trace' do
         authorize_read_builds!
 
@@ -115,13 +123,12 @@ module API
         body trace
       end
 
-      # Cancel a specific build of a project
-      #
-      # parameters:
-      #   id (required) - the id of a project
-      #   build_id (required) - the id of a build
-      # example request:
-      #   post /projects/:id/build/:build_id/cancel
+      desc 'Cancel a specific build of a project' do
+        success Entities::Build
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       post ':id/builds/:build_id/cancel' do
         authorize_update_builds!
 
@@ -133,13 +140,12 @@ module API
                        user_can_download_artifacts: can?(current_user, :read_build, user_project)
       end
 
-      # Retry a specific build of a project
-      #
-      # parameters:
-      #   id (required) - the id of a project
-      #   build_id (required) - the id of a build
-      # example request:
-      #   post /projects/:id/build/:build_id/retry
+      desc 'Retry a specific build of a project' do
+        success Entities::Build
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       post ':id/builds/:build_id/retry' do
         authorize_update_builds!
 
@@ -152,13 +158,12 @@ module API
                        user_can_download_artifacts: can?(current_user, :read_build, user_project)
       end
 
-      # Erase build (remove artifacts and build trace)
-      #
-      # Parameters:
-      #   id (required) - the id of a project
-      #   build_id (required) - the id of a build
-      # example Request:
-      #  post  /projects/:id/build/:build_id/erase
+      desc 'Erase build (remove artifacts and build trace)' do
+        success Entities::Build
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       post ':id/builds/:build_id/erase' do
         authorize_update_builds!
 
@@ -170,13 +175,12 @@ module API
                        user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
       end
 
-      # Keep the artifacts to prevent them from being deleted
-      #
-      # Parameters:
-      #   id (required) - the id of a project
-      #   build_id (required) - The ID of a build
-      # Example Request:
-      #   POST /projects/:id/builds/:build_id/artifacts/keep
+      desc 'Keep the artifacts to prevent them from being deleted' do
+        success Entities::Build
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a build'
+      end
       post ':id/builds/:build_id/artifacts/keep' do
         authorize_update_builds!
 
@@ -235,14 +239,6 @@ module API
         return builds if scope.nil? || scope.empty?
 
         available_statuses = ::CommitStatus::AVAILABLE_STATUSES
-        scope =
-          if scope.is_a?(String)
-            [scope]
-          elsif scope.is_a?(Hashie::Mash)
-            scope.values
-          else
-            ['unknown']
-          end
 
         unknown = scope - available_statuses
         render_api_error!('Scope contains invalid value(s)', 400) unless unknown.empty?
diff --git a/lib/api/commit_statuses.rb b/lib/api/commit_statuses.rb
index dfbdd597d29..f54d4f06627 100644
--- a/lib/api/commit_statuses.rb
+++ b/lib/api/commit_statuses.rb
@@ -6,17 +6,17 @@ module API
     resource :projects do
       before { authenticate! }
 
-      # Get a commit's statuses
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The commit hash
-      #   ref (optional) - The ref
-      #   stage (optional) - The stage
-      #   name (optional) - The name
-      #   all (optional) - Show all statuses, default: false
-      # Examples:
-      #   GET /projects/:id/repository/commits/:sha/statuses
+      desc "Get a commit's statuses" do
+        success Entities::CommitStatus
+      end
+      params do
+        requires :id,    type: String, desc: 'The ID of a project'
+        requires :sha,   type: String, desc: 'The commit hash'
+        optional :ref,   type: String, desc: 'The ref'
+        optional :stage, type: String, desc: 'The stage'
+        optional :name,  type: String, desc: 'The name'
+        optional :all,   type: String, desc: 'Show all statuses, default: false'
+      end
       get ':id/repository/commits/:sha/statuses' do
         authorize!(:read_commit_status, user_project)
 
@@ -31,22 +31,23 @@ module API
         present paginate(statuses), with: Entities::CommitStatus
       end
 
-      # Post status to commit
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The commit hash
-      #   ref (optional) - The ref
-      #   state (required) - The state of the status. Can be: pending, running, success, failed or canceled
-      #   target_url (optional) - The target URL to associate with this status
-      #   description (optional) - A short description of the status
-      #   name or context (optional) - A string label to differentiate this status from the status of other systems. Default: "default"
-      # Examples:
-      #   POST /projects/:id/statuses/:sha
+      desc 'Post status to a commit' do
+        success Entities::CommitStatus
+      end
+      params do
+        requires :id,          type: String,  desc: 'The ID of a project'
+        requires :sha,         type: String,  desc: 'The commit hash'
+        requires :state,       type: String,  desc: 'The state of the status',
+                               values: ['pending', 'running', 'success', 'failed', 'canceled']
+        optional :ref,         type: String,  desc: 'The ref'
+        optional :target_url,  type: String,  desc: 'The target URL to associate with this status'
+        optional :description, type: String,  desc: 'A short description of the status'
+        optional :name,        type: String,  desc: 'A string label to differentiate this status from the status of other systems. Default: "default"'
+        optional :context,     type: String,  desc: 'A string label to differentiate this status from the status of other systems. Default: "default"'
+      end
       post ':id/statuses/:sha' do
         authorize! :create_commit_status, user_project
-        required_attributes! [:state]
-        attrs = attributes_for_keys [:target_url, :description]
+
         commit = @project.commit(params[:sha])
         not_found! 'Commit' unless commit
 
@@ -66,9 +67,14 @@ module API
         pipeline = @project.ensure_pipeline(ref, commit.sha, current_user)
 
         status = GenericCommitStatus.running_or_pending.find_or_initialize_by(
-          project: @project, pipeline: pipeline,
-          user: current_user, name: name, ref: ref)
-        status.attributes = attrs
+          project: @project,
+          pipeline: pipeline,
+          user: current_user,
+          name: name,
+          ref: ref,
+          target_url: params[:target_url],
+          description: params[:description]
+        )
 
         begin
           case params[:state].to_s
diff --git a/lib/api/commits.rb b/lib/api/commits.rb
index b4eaf1813d4..2f2cf769481 100644
--- a/lib/api/commits.rb
+++ b/lib/api/commits.rb
@@ -6,102 +6,149 @@ module API
     before { authenticate! }
     before { authorize! :download_code, user_project }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
-      # Get a project repository commits
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   ref_name (optional) - The name of a repository branch or tag, if not given the default branch is used
-      #   since (optional) - Only commits after or in this date will be returned
-      #   until (optional) - Only commits before or in this date will be returned
-      # Example Request:
-      #   GET /projects/:id/repository/commits
+      desc 'Get a project repository commits' do
+        success Entities::RepoCommit
+      end
+      params do
+        optional :ref_name, type: String, desc: 'The name of a repository branch or tag, if not given the default branch is used'
+        optional :since,    type: String, desc: 'Only commits after or in this date will be returned'
+        optional :until,    type: String, desc: 'Only commits before or in this date will be returned'
+        optional :page,     type: Integer, default: 0, desc: 'The page for pagination'
+        optional :per_page, type: Integer, default: 20, desc: 'The number of results per page'
+        optional :path,     type: String, desc: 'The file path'
+      end
       get ":id/repository/commits" do
+        # TODO remove the next line for 9.0, use DateTime type in the params block
         datetime_attributes! :since, :until
 
-        page = (params[:page] || 0).to_i
-        per_page = (params[:per_page] || 20).to_i
         ref = params[:ref_name] || user_project.try(:default_branch) || 'master'
-        after = params[:since]
-        before = params[:until]
+        offset = params[:page] * params[:per_page]
+
+        commits = user_project.repository.commits(ref,
+                                                  path: params[:path],
+                                                  limit: params[:per_page],
+                                                  offset: offset,
+                                                  after: params[:since],
+                                                  before: params[:until])
 
-        commits = user_project.repository.commits(ref, limit: per_page, offset: page * per_page, after: after, before: before)
         present commits, with: Entities::RepoCommit
       end
 
-      # Get a specific commit of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The commit hash or name of a repository branch or tag
-      # Example Request:
-      #   GET /projects/:id/repository/commits/:sha
+      desc 'Commit multiple file changes as one commit' do
+        success Entities::RepoCommitDetail
+        detail 'This feature was introduced in GitLab 8.13'
+      end
+      params do
+        requires :id, type: Integer, desc: 'The project ID'
+        requires :branch_name, type: String, desc: 'The name of branch'
+        requires :commit_message, type: String, desc: 'Commit message'
+        requires :actions, type: Array, desc: 'Actions to perform in commit'
+        optional :author_email, type: String, desc: 'Author email for commit'
+        optional :author_name, type: String, desc: 'Author name for commit'
+      end
+      post ":id/repository/commits" do
+        authorize! :push_code, user_project
+
+        attrs = declared(params)
+        attrs[:source_branch] = attrs[:branch_name]
+        attrs[:target_branch] = attrs[:branch_name]
+        attrs[:actions].map! do |action|
+          action[:action] = action[:action].to_sym
+          action[:file_path].slice!(0) if action[:file_path] && action[:file_path].start_with?('/')
+          action[:previous_path].slice!(0) if action[:previous_path] && action[:previous_path].start_with?('/')
+          action
+        end
+
+        result = ::Files::MultiService.new(user_project, current_user, attrs).execute
+
+        if result[:status] == :success
+          commit_detail = user_project.repository.commits(result[:result], limit: 1).first
+          present commit_detail, with: Entities::RepoCommitDetail
+        else
+          render_api_error!(result[:message], 400)
+        end
+      end
+
+      desc 'Get a specific commit of a project' do
+        success Entities::RepoCommitDetail
+        failure [[404, 'Not Found']]
+      end
+      params do
+        requires :sha, type: String, desc: 'A commit sha, or the name of a branch or tag'
+      end
       get ":id/repository/commits/:sha" do
-        sha = params[:sha]
-        commit = user_project.commit(sha)
+        commit = user_project.commit(params[:sha])
+
         not_found! "Commit" unless commit
+
         present commit, with: Entities::RepoCommitDetail
       end
 
-      # Get the diff for a specific commit of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The commit or branch name
-      # Example Request:
-      #   GET /projects/:id/repository/commits/:sha/diff
+      desc 'Get the diff for a specific commit of a project' do
+        failure [[404, 'Not Found']]
+      end
+      params do
+        requires :sha, type: String, desc: 'A commit sha, or the name of a branch or tag'
+      end
       get ":id/repository/commits/:sha/diff" do
-        sha = params[:sha]
-        commit = user_project.commit(sha)
+        commit = user_project.commit(params[:sha])
+
         not_found! "Commit" unless commit
+
         commit.raw_diffs.to_a
       end
 
-      # Get a commit's comments
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The commit hash
-      # Examples:
-      #   GET /projects/:id/repository/commits/:sha/comments
+      desc "Get a commit's comments" do
+        success Entities::CommitNote
+        failure [[404, 'Not Found']]
+      end
+      params do
+        requires :sha, type: String, desc: 'A commit sha, or the name of a branch or tag'
+        optional :per_page, type: Integer, desc: 'The amount of items per page for paginaion'
+        optional :page, type: Integer, desc: 'The page number for pagination'
+      end
       get ':id/repository/commits/:sha/comments' do
-        sha = params[:sha]
-        commit = user_project.commit(sha)
+        commit = user_project.commit(params[:sha])
+
         not_found! 'Commit' unless commit
         notes = Note.where(commit_id: commit.id).order(:created_at)
+
         present paginate(notes), with: Entities::CommitNote
       end
 
-      # Post comment to commit
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   sha (required) - The commit hash
-      #   note (required) - Text of comment
-      #   path (optional) - The file path
-      #   line (optional) - The line number
-      #   line_type (optional) - The type of line (new or old)
-      # Examples:
-      #   POST /projects/:id/repository/commits/:sha/comments
+      desc 'Post comment to commit' do
+        success Entities::CommitNote
+      end
+      params do
+        requires :sha, type: String, regexp: /\A\h{6,40}\z/, desc: "The commit's SHA"
+        requires :note, type: String, desc: 'The text of the comment'
+        optional :path, type: String, desc: 'The file path'
+        given :path do
+          requires :line, type: Integer, desc: 'The line number'
+          requires :line_type, type: String, values: ['new', 'old'], default: 'new', desc: 'The type of the line'
+        end
+      end
       post ':id/repository/commits/:sha/comments' do
-        required_attributes! [:note]
-
-        sha = params[:sha]
-        commit = user_project.commit(sha)
+        commit = user_project.commit(params[:sha])
         not_found! 'Commit' unless commit
+
         opts = {
           note: params[:note],
           noteable_type: 'Commit',
           commit_id: commit.id
         }
 
-        if params[:path] && params[:line] && params[:line_type]
+        if params[:path]
           commit.raw_diffs(all_diffs: true).each do |diff|
             next unless diff.new_path == params[:path]
             lines = Gitlab::Diff::Parser.new.parse(diff.diff.each_line)
 
             lines.each do |line|
-              next unless line.new_pos == params[:line].to_i && line.type == params[:line_type]
+              next unless line.new_pos == params[:line] && line.type == params[:line_type]
               break opts[:line_code] = Gitlab::Diff::LineCode.generate(diff.new_path, line.new_pos, line.old_pos)
             end
 
diff --git a/lib/api/entities.rb b/lib/api/entities.rb
index b081cb8e520..e1995aa6f4b 100644
--- a/lib/api/entities.rb
+++ b/lib/api/entities.rb
@@ -344,7 +344,7 @@ module API
     end
 
     class ProjectGroupLink < Grape::Entity
-      expose :id, :project_id, :group_id, :group_access
+      expose :id, :project_id, :group_id, :group_access, :expires_at
     end
 
     class Todo < Grape::Entity
@@ -433,8 +433,11 @@ module API
       end
     end
 
-    class Label < Grape::Entity
+    class LabelBasic < Grape::Entity
       expose :name, :color, :description
+    end
+
+    class Label < LabelBasic
       expose :open_issues_count, :closed_issues_count, :open_merge_requests_count
 
       expose :subscribed do |label, options|
@@ -442,6 +445,19 @@ module API
       end
     end
 
+    class List < Grape::Entity
+      expose :id
+      expose :label, using: Entities::LabelBasic
+      expose :position
+    end
+
+    class Board < Grape::Entity
+      expose :id
+      expose :lists, using: Entities::List do |board|
+        board.lists.destroyable
+      end
+    end
+
     class Compare < Grape::Entity
       expose :commit, using: Entities::RepoCommit do |compare, options|
         Commit.decorate(compare.commits, nil).last
@@ -495,6 +511,8 @@ module API
       expose :after_sign_out_path
       expose :container_registry_token_expire_delay
       expose :repository_storage
+      expose :koding_enabled
+      expose :koding_url
     end
 
     class Release < Grape::Entity
@@ -546,6 +564,10 @@ module API
       expose :filename, :size
     end
 
+    class PipelineBasic < Grape::Entity
+      expose :id, :sha, :ref, :status
+    end
+
     class Build < Grape::Entity
       expose :id, :status, :stage, :name, :ref, :tag, :coverage
       expose :created_at, :started_at, :finished_at
@@ -553,6 +575,7 @@ module API
       expose :artifacts_file, using: BuildArtifactFile, if: -> (build, opts) { build.artifacts? }
       expose :commit, with: RepoCommit
       expose :runner, with: Runner
+      expose :pipeline, with: PipelineBasic
     end
 
     class Trigger < Grape::Entity
@@ -563,8 +586,8 @@ module API
       expose :key, :value
     end
 
-    class Pipeline < Grape::Entity
-      expose :id, :status, :ref, :sha, :before_sha, :tag, :yaml_errors
+    class Pipeline < PipelineBasic
+      expose :before_sha, :tag, :yaml_errors
 
       expose :user, with: Entities::UserBasic
       expose :created_at, :updated_at, :started_at, :finished_at, :committed_at
diff --git a/lib/api/groups.rb b/lib/api/groups.rb
index e9abd53e62b..8ca4cfa68cd 100644
--- a/lib/api/groups.rb
+++ b/lib/api/groups.rb
@@ -6,6 +6,8 @@ module API
     resource :groups do
       # Get a groups list
       #
+      # Parameters:
+      #   skip_groups (optional) - Array of group ids to exclude from list
       # Example Request:
       #  GET /groups
       get do
@@ -16,6 +18,7 @@ module API
                   end
 
         @groups = @groups.search(params[:search]) if params[:search].present?
+        @groups = @groups.where.not(id: params[:skip_groups]) if params[:skip_groups].present?
         @groups = paginate @groups
         present @groups, with: Entities::Group
       end
diff --git a/lib/api/helpers.rb b/lib/api/helpers.rb
index 9d71e90075a..d05841def89 100644
--- a/lib/api/helpers.rb
+++ b/lib/api/helpers.rb
@@ -21,8 +21,11 @@ module API
     end
 
     # Check the Rails session for valid authentication details
+    #
+    # Until CSRF protection is added to the API, disallow this method for
+    # state-changing endpoints
     def find_user_from_warden
-      warden ? warden.authenticate : nil
+      warden.try(:authenticate) if %w[GET HEAD].include?(env['REQUEST_METHOD'])
     end
 
     def find_user_by_private_token
@@ -68,6 +71,10 @@ module API
       @project ||= find_project(params[:id])
     end
 
+    def available_labels
+      @available_labels ||= LabelsFinder.new(current_user, project_id: user_project.id).execute
+    end
+
     def find_project(id)
       project = Project.find_with_namespace(id) || Project.find_by(id: id)
 
@@ -115,7 +122,7 @@ module API
     end
 
     def find_project_label(id)
-      label = user_project.labels.find_by_id(id) || user_project.labels.find_by_title(id)
+      label = available_labels.find_by_id(id) || available_labels.find_by_title(id)
       label || not_found!('Label')
     end
 
@@ -194,16 +201,11 @@ module API
     def validate_label_params(params)
       errors = {}
 
-      if params[:labels].present?
-        params[:labels].split(',').each do |label_name|
-          label = user_project.labels.create_with(
-            color: Label::DEFAULT_COLOR).find_or_initialize_by(
-              title: label_name.strip)
+      params[:labels].to_s.split(',').each do |label_name|
+        label = available_labels.find_or_initialize_by(title: label_name.strip)
+        next if label.valid?
 
-          if label.invalid?
-            errors[label.title] = label.errors
-          end
-        end
+        errors[label.title] = label.errors
       end
 
       errors
@@ -430,7 +432,7 @@ module API
     end
 
     def secret_token
-      File.read(Gitlab.config.gitlab_shell.secret_file).chomp
+      Gitlab::Shell.secret_token
     end
 
     def send_git_blob(repository, blob)
diff --git a/lib/api/keys.rb b/lib/api/keys.rb
index 2b723b79504..767f27ef334 100644
--- a/lib/api/keys.rb
+++ b/lib/api/keys.rb
@@ -4,10 +4,9 @@ module API
     before { authenticate! }
 
     resource :keys do
-      # Get single ssh key by id. Only available to admin users.
-      #
-      # Example Request:
-      #   GET /keys/:id
+      desc 'Get single ssh key by id. Only available to admin users' do
+        success Entities::SSHKeyWithUser
+      end
       get ":id" do
         authenticated_as_admin!
 
diff --git a/lib/api/labels.rb b/lib/api/labels.rb
index c806829d69e..326e1e7ae00 100644
--- a/lib/api/labels.rb
+++ b/lib/api/labels.rb
@@ -3,37 +3,32 @@ module API
   class Labels < Grape::API
     before { authenticate! }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
-      # Get all labels of the project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      # Example Request:
-      #   GET /projects/:id/labels
+      desc 'Get all labels of the project' do
+        success Entities::Label
+      end
       get ':id/labels' do
-        present user_project.labels, with: Entities::Label, current_user: current_user
+        present available_labels, with: Entities::Label, current_user: current_user
       end
 
-      # Creates a new label
-      #
-      # Parameters:
-      #   id    (required)       - The ID of a project
-      #   name  (required)       - The name of the label to be created
-      #   color (required)       - Color of the label given in 6-digit hex
-      #                            notation with leading '#' sign (e.g. #FFAABB)
-      #   description (optional) - The description of label to be created
-      # Example Request:
-      #   POST /projects/:id/labels
+      desc 'Create a new label' do
+        success Entities::Label
+      end
+      params do
+        requires :name, type: String, desc: 'The name of the label to be created'
+        requires :color, type: String, desc: "The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)"
+        optional :description, type: String, desc: 'The description of label to be created'
+      end
       post ':id/labels' do
         authorize! :admin_label, user_project
-        required_attributes! [:name, :color]
-
-        attrs = attributes_for_keys [:name, :color, :description]
-        label = user_project.find_label(attrs[:name])
 
+        label = user_project.find_label(params[:name])
         conflict!('Label already exists') if label
 
-        label = user_project.labels.create(attrs)
+        label = user_project.labels.create(declared(params, include_parent_namespaces: false).to_h)
 
         if label.valid?
           present label, with: Entities::Label, current_user: current_user
@@ -42,54 +37,44 @@ module API
         end
       end
 
-      # Deletes an existing label
-      #
-      # Parameters:
-      #   id    (required) - The ID of a project
-      #   name  (required) - The name of the label to be deleted
-      #
-      # Example Request:
-      #   DELETE /projects/:id/labels
+      desc 'Delete an existing label' do
+        success Entities::Label
+      end
+      params do
+        requires :name, type: String, desc: 'The name of the label to be deleted'
+      end
       delete ':id/labels' do
         authorize! :admin_label, user_project
-        required_attributes! [:name]
 
         label = user_project.find_label(params[:name])
         not_found!('Label') unless label
 
-        label.destroy
+        present label.destroy, with: Entities::Label, current_user: current_user
       end
 
-      # Updates an existing label. At least one optional parameter is required.
-      #
-      # Parameters:
-      #   id        (required)   - The ID of a project
-      #   name      (required)   - The name of the label to be deleted
-      #   new_name  (optional)   - The new name of the label
-      #   color     (optional)   - Color of the label given in 6-digit hex
-      #                            notation with leading '#' sign (e.g. #FFAABB)
-      #   description (optional) - The description of label to be created
-      # Example Request:
-      #   PUT /projects/:id/labels
+      desc 'Update an existing label. At least one optional parameter is required.' do
+        success Entities::Label
+      end
+      params do
+        requires :name,  type: String, desc: 'The name of the label to be updated'
+        optional :new_name, type: String, desc: 'The new name of the label'
+        optional :color, type: String, desc: "The new color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)"
+        optional :description, type: String, desc: 'The new description of label'
+        at_least_one_of :new_name, :color, :description
+      end
       put ':id/labels' do
         authorize! :admin_label, user_project
-        required_attributes! [:name]
 
         label = user_project.find_label(params[:name])
         not_found!('Label not found') unless label
 
-        attrs = attributes_for_keys [:new_name, :color, :description]
-
-        if attrs.empty?
-          render_api_error!('Required parameters "new_name" or "color" ' \
-                            'missing',
-                            400)
-        end
-
+        update_params = declared(params,
+                                 include_parent_namespaces: false,
+                                 include_missing: false).to_h
         # Rename new name to the actual label attribute name
-        attrs[:name] = attrs.delete(:new_name) if attrs.key?(:new_name)
+        update_params['name'] = update_params.delete('new_name') if update_params.key?('new_name')
 
-        if label.update(attrs)
+        if label.update(update_params)
           present label, with: Entities::Label, current_user: current_user
         else
           render_validation_error!(label)
diff --git a/lib/api/license_templates.rb b/lib/api/license_templates.rb
deleted file mode 100644
index d0552299ed0..00000000000
--- a/lib/api/license_templates.rb
+++ /dev/null
@@ -1,58 +0,0 @@
-module API
-  # License Templates API
-  class LicenseTemplates < Grape::API
-    PROJECT_TEMPLATE_REGEX =
-      /[\<\{\[]
-        (project|description|
-        one\sline\s.+\swhat\sit\sdoes\.) # matching the start and end is enough here
-      [\>\}\]]/xi.freeze
-    YEAR_TEMPLATE_REGEX = /[<{\[](year|yyyy)[>}\]]/i.freeze
-    FULLNAME_TEMPLATE_REGEX =
-      /[\<\{\[]
-        (fullname|name\sof\s(author|copyright\sowner))
-      [\>\}\]]/xi.freeze
-
-    # Get the list of the available license templates
-    #
-    # Parameters:
-    #   popular - Filter licenses to only the popular ones
-    #
-    # Example Request:
-    #   GET /licenses
-    #   GET /licenses?popular=1
-    get 'licenses' do
-      options = {
-        featured: params[:popular].present? ? true : nil
-      }
-      present Licensee::License.all(options), with: Entities::RepoLicense
-    end
-
-    # Get text for specific license
-    #
-    # Parameters:
-    #   key (required) - The key of a license
-    #   project        - Copyrighted project name
-    #   fullname       - Full name of copyright holder
-    #
-    # Example Request:
-    #   GET /licenses/mit
-    #
-    get 'licenses/:key', requirements: { key: /[\w\.-]+/ } do
-      required_attributes! [:key]
-
-      not_found!('License') unless Licensee::License.find(params[:key])
-
-      # We create a fresh Licensee::License object since we'll modify its
-      # content in place below.
-      license = Licensee::License.new(params[:key])
-
-      license.content.gsub!(YEAR_TEMPLATE_REGEX, Time.now.year.to_s)
-      license.content.gsub!(PROJECT_TEMPLATE_REGEX, params[:project]) if params[:project].present?
-
-      fullname = params[:fullname].presence || current_user.try(:name)
-      license.content.gsub!(FULLNAME_TEMPLATE_REGEX, fullname) if fullname
-
-      present license, with: Entities::RepoLicense
-    end
-  end
-end
diff --git a/lib/api/members.rb b/lib/api/members.rb
index 37f0a6512f4..b80818f0eb6 100644
--- a/lib/api/members.rb
+++ b/lib/api/members.rb
@@ -5,16 +5,16 @@ module API
     helpers ::API::Helpers::MembersHelpers
 
     %w[group project].each do |source_type|
+      params do
+        requires :id, type: String, desc: "The #{source_type} ID"
+      end
       resource source_type.pluralize do
-        # Get a list of group/project members viewable by the authenticated user.
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   query         - Query string
-        #
-        # Example Request:
-        #   GET /groups/:id/members
-        #   GET /projects/:id/members
+        desc 'Gets a list of group or project members viewable by the authenticated user.' do
+          success Entities::Member
+        end
+        params do
+          optional :query, type: String, desc: 'A query string to search for members'
+        end
         get ":id/members" do
           source = find_source(source_type, params[:id])
 
@@ -25,15 +25,12 @@ module API
           present users, with: Entities::Member, source: source
         end
 
-        # Get a group/project member
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   user_id (required) - The user ID of the member
-        #
-        # Example Request:
-        #   GET /groups/:id/members/:user_id
-        #   GET /projects/:id/members/:user_id
+        desc 'Gets a member of a group or project.' do
+          success Entities::Member
+        end
+        params do
+          requires :user_id, type: Integer, desc: 'The user ID of the member'
+        end
         get ":id/members/:user_id" do
           source = find_source(source_type, params[:id])
 
@@ -43,48 +40,34 @@ module API
           present member.user, with: Entities::Member, member: member
         end
 
-        # Add a new group/project member
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   user_id (required) - The user ID of the new member
-        #   access_level (required) - A valid access level
-        #   expires_at (optional) - Date string in the format YEAR-MONTH-DAY
-        #
-        # Example Request:
-        #   POST /groups/:id/members
-        #   POST /projects/:id/members
+        desc 'Adds a member to a group or project.' do
+          success Entities::Member
+        end
+        params do
+          requires :user_id, type: Integer, desc: 'The user ID of the new member'
+          requires :access_level, type: Integer, desc: 'A valid access level (defaults: `30`, developer access level)'
+          optional :expires_at, type: DateTime, desc: 'Date string in the format YEAR-MONTH-DAY'
+        end
         post ":id/members" do
           source = find_source(source_type, params[:id])
           authorize_admin_source!(source_type, source)
-          required_attributes! [:user_id, :access_level]
-
-          access_requester = source.requesters.find_by(user_id: params[:user_id])
-          if access_requester
-            # We pass current_user = access_requester so that the requester doesn't
-            # receive a "access denied" email
-            ::Members::DestroyService.new(access_requester, access_requester.user).execute
-          end
 
           member = source.members.find_by(user_id: params[:user_id])
 
-          # This is to ensure back-compatibility but 409 behavior should be used
-          # for both project and group members in 9.0!
+          # We need this explicit check because `source.add_user` doesn't
+          # currently return the member created so it would return 201 even if
+          # the member already existed...
+          # The `source_type == 'group'` check is to ensure back-compatibility
+          # but 409 behavior should be used for both project and group members in 9.0!
           conflict!('Member already exists') if source_type == 'group' && member
 
           unless member
-            source.add_user(params[:user_id], params[:access_level], current_user: current_user, expires_at: params[:expires_at])
-            member = source.members.find_by(user_id: params[:user_id])
+            member = source.add_user(params[:user_id], params[:access_level], current_user: current_user, expires_at: params[:expires_at])
           end
 
-          if member
+          if member.persisted? && member.valid?
             present member.user, with: Entities::Member, member: member
           else
-            # Since `source.add_user` doesn't return a member object, we have to
-            # build a new one and populate its errors in order to render them.
-            member = source.members.build(attributes_for_keys([:user_id, :access_level, :expires_at]))
-            member.valid? # populate the errors
-
             # This is to ensure back-compatibility but 400 behavior should be used
             # for all validation errors in 9.0!
             render_api_error!('Access level is not known', 422) if member.errors.key?(:access_level)
@@ -92,21 +75,17 @@ module API
           end
         end
 
-        # Update a group/project member
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   user_id (required) - The user ID of the member
-        #   access_level (required) - A valid access level
-        #   expires_at (optional) - Date string in the format YEAR-MONTH-DAY
-        #
-        # Example Request:
-        #   PUT /groups/:id/members/:user_id
-        #   PUT /projects/:id/members/:user_id
+        desc 'Updates a member of a group or project.' do
+          success Entities::Member
+        end
+        params do
+          requires :user_id, type: Integer, desc: 'The user ID of the new member'
+          requires :access_level, type: Integer, desc: 'A valid access level'
+          optional :expires_at, type: DateTime, desc: 'Date string in the format YEAR-MONTH-DAY'
+        end
         put ":id/members/:user_id" do
           source = find_source(source_type, params[:id])
           authorize_admin_source!(source_type, source)
-          required_attributes! [:user_id, :access_level]
 
           member = source.members.find_by!(user_id: params[:user_id])
           attrs = attributes_for_keys [:access_level, :expires_at]
@@ -121,18 +100,12 @@ module API
           end
         end
 
-        # Remove a group/project member
-        #
-        # Parameters:
-        #   id (required) - The group/project ID
-        #   user_id (required) - The user ID of the member
-        #
-        # Example Request:
-        #   DELETE /groups/:id/members/:user_id
-        #   DELETE /projects/:id/members/:user_id
+        desc 'Removes a user from a group or project.'
+        params do
+          requires :user_id, type: Integer, desc: 'The user ID of the member'
+        end
         delete ":id/members/:user_id" do
           source = find_source(source_type, params[:id])
-          required_attributes! [:user_id]
 
           # This is to ensure back-compatibility but find_by! should be used
           # in that casse in 9.0!
@@ -147,7 +120,7 @@ module API
           if member.nil?
             { message: "Access revoked", id: params[:user_id].to_i }
           else
-            ::Members::DestroyService.new(member, current_user).execute
+            ::Members::DestroyService.new(source, current_user, declared(params)).execute
 
             present member.user, with: Entities::Member, member: member
           end
diff --git a/lib/api/merge_requests.rb b/lib/api/merge_requests.rb
index 2b685621da9..bf8504e1101 100644
--- a/lib/api/merge_requests.rb
+++ b/lib/api/merge_requests.rb
@@ -86,14 +86,11 @@ module API
           render_api_error!({ labels: errors }, 400)
         end
 
+        attrs[:labels] = params[:labels] if params[:labels]
+
         merge_request = ::MergeRequests::CreateService.new(user_project, current_user, attrs).execute
 
         if merge_request.valid?
-          # Find or create labels and attach to issue
-          if params[:labels].present?
-            merge_request.add_labels_by_names(params[:labels].split(","))
-          end
-
           present merge_request, with: Entities::MergeRequest, current_user: current_user
         else
           handle_merge_request_errors! merge_request.errors
@@ -195,15 +192,11 @@ module API
             render_api_error!({ labels: errors }, 400)
           end
 
+          attrs[:labels] = params[:labels] if params[:labels]
+
           merge_request = ::MergeRequests::UpdateService.new(user_project, current_user, attrs).execute(merge_request)
 
           if merge_request.valid?
-            # Find or create labels and attach to issue
-            unless params[:labels].nil?
-              merge_request.remove_labels
-              merge_request.add_labels_by_names(params[:labels].split(","))
-            end
-
             present merge_request, with: Entities::MergeRequest, current_user: current_user
           else
             handle_merge_request_errors! merge_request.errors
diff --git a/lib/api/milestones.rb b/lib/api/milestones.rb
index 7a0cb7c99f3..9b73f6826cf 100644
--- a/lib/api/milestones.rb
+++ b/lib/api/milestones.rb
@@ -108,8 +108,7 @@ module API
 
         finder_params = {
           project_id: user_project.id,
-          milestone_title: @milestone.title,
-          state: 'all'
+          milestone_title: @milestone.title
         }
 
         issues = IssuesFinder.new(current_user, finder_params).execute
diff --git a/lib/api/namespaces.rb b/lib/api/namespaces.rb
index 25dc41a3349..cd398274507 100644
--- a/lib/api/namespaces.rb
+++ b/lib/api/namespaces.rb
@@ -4,20 +4,18 @@ module API
     before { authenticate! }
 
     resource :namespaces do
-      # Get a namespaces list
-      #
-      # Example Request:
-      #  GET /namespaces
+      desc 'Get a namespaces list' do
+        success Entities::Namespace
+      end
+      params do
+        optional :search, type: String, desc: "Search query for namespaces"
+      end
       get do
-        @namespaces = if current_user.admin?
-                        Namespace.all
-                      else
-                        current_user.namespaces
-                      end
-        @namespaces = @namespaces.search(params[:search]) if params[:search].present?
-        @namespaces = paginate @namespaces
+        namespaces = current_user.admin? ? Namespace.all : current_user.namespaces
+
+        namespaces = namespaces.search(params[:search]) if params[:search].present?
 
-        present @namespaces, with: Entities::Namespace
+        present paginate(namespaces), with: Entities::Namespace
       end
     end
   end
diff --git a/lib/api/projects.rb b/lib/api/projects.rb
index 6d99617b56f..da16e24d7ea 100644
--- a/lib/api/projects.rb
+++ b/lib/api/projects.rb
@@ -22,14 +22,25 @@ module API
       # Example Request:
       #   GET /projects
       get do
-        @projects = current_user.authorized_projects
-        @projects = filter_projects(@projects)
-        @projects = paginate @projects
-        if params[:simple]
-          present @projects, with: Entities::BasicProjectDetails, user: current_user
-        else
-          present @projects, with: Entities::ProjectWithAccess, user: current_user
-        end
+        projects = current_user.authorized_projects
+        projects = filter_projects(projects)
+        projects = paginate projects
+        entity = params[:simple] ? Entities::BasicProjectDetails : Entities::ProjectWithAccess
+
+        present projects, with: entity, user: current_user
+      end
+
+      # Get a list of visible projects for authenticated user
+      #
+      # Example Request:
+      #   GET /projects/visible
+      get '/visible' do
+        projects = ProjectsFinder.new.execute(current_user)
+        projects = filter_projects(projects)
+        projects = paginate projects
+        entity = params[:simple] ? Entities::BasicProjectDetails : Entities::ProjectWithAccess
+
+        present projects, with: entity, user: current_user
       end
 
       # Get an owned projects list for authenticated user
@@ -37,10 +48,10 @@ module API
       # Example Request:
       #   GET /projects/owned
       get '/owned' do
-        @projects = current_user.owned_projects
-        @projects = filter_projects(@projects)
-        @projects = paginate @projects
-        present @projects, with: Entities::ProjectWithAccess, user: current_user
+        projects = current_user.owned_projects
+        projects = filter_projects(projects)
+        projects = paginate projects
+        present projects, with: Entities::ProjectWithAccess, user: current_user
       end
 
       # Gets starred project for the authenticated user
@@ -48,10 +59,10 @@ module API
       # Example Request:
       #   GET /projects/starred
       get '/starred' do
-        @projects = current_user.viewable_starred_projects
-        @projects = filter_projects(@projects)
-        @projects = paginate @projects
-        present @projects, with: Entities::Project, user: current_user
+        projects = current_user.viewable_starred_projects
+        projects = filter_projects(projects)
+        projects = paginate projects
+        present projects, with: Entities::Project, user: current_user
       end
 
       # Get all projects for admin user
@@ -60,10 +71,10 @@ module API
       #   GET /projects/all
       get '/all' do
         authenticated_as_admin!
-        @projects = Project.all
-        @projects = filter_projects(@projects)
-        @projects = paginate @projects
-        present @projects, with: Entities::ProjectWithAccess, user: current_user
+        projects = Project.all
+        projects = filter_projects(projects)
+        projects = paginate projects
+        present projects, with: Entities::ProjectWithAccess, user: current_user
       end
 
       # Get a single project
@@ -393,23 +404,30 @@ module API
       # Share project with group
       #
       # Parameters:
-      #   id (required) - The ID of a project
-      #   group_id (required) - The ID of a group
+      #   id (required)           - The ID of a project
+      #   group_id (required)     - The ID of a group
       #   group_access (required) - Level of permissions for sharing
+      #   expires_at (optional)   - Share expiration date
       #
       # Example Request:
       #   POST /projects/:id/share
       post ":id/share" do
         authorize! :admin_project, user_project
         required_attributes! [:group_id, :group_access]
+        attrs = attributes_for_keys [:group_id, :group_access, :expires_at]
+
+        group = Group.find_by_id(attrs[:group_id])
+
+        unless group && can?(current_user, :read_group, group)
+          not_found!('Group')
+        end
 
         unless user_project.allowed_to_share_with_group?
           return render_api_error!("The project sharing with group is disabled", 400)
         end
 
-        link = user_project.project_group_links.new
-        link.group_id = params[:group_id]
-        link.group_access = params[:group_access]
+        link = user_project.project_group_links.new(attrs)
+
         if link.save
           present link, with: Entities::ProjectGroupLink
         else
diff --git a/lib/api/system_hooks.rb b/lib/api/system_hooks.rb
index 22b8f90dc5c..794e34874f4 100644
--- a/lib/api/system_hooks.rb
+++ b/lib/api/system_hooks.rb
@@ -7,38 +7,36 @@ module API
     end
 
     resource :hooks do
-      # Get the list of system hooks
-      #
-      # Example Request:
-      #   GET /hooks
+      desc 'Get the list of system hooks' do
+        success Entities::Hook
+      end
       get do
-        @hooks = SystemHook.all
-        present @hooks, with: Entities::Hook
+        hooks = SystemHook.all
+        present hooks, with: Entities::Hook
       end
 
-      # Create new system hook
-      #
-      # Parameters:
-      #   url (required) - url for system hook
-      # Example Request
-      #   POST /hooks
+      desc 'Create a new system hook' do
+        success Entities::Hook
+      end
+      params do
+        requires :url, type: String, desc: 'The URL for the system hook'
+      end
       post do
-        attrs = attributes_for_keys [:url]
-        required_attributes! [:url]
-        @hook = SystemHook.new attrs
-        if @hook.save
-          present @hook, with: Entities::Hook
+        hook = SystemHook.new declared(params).to_h
+
+        if hook.save
+          present hook, with: Entities::Hook
         else
           not_found!
         end
       end
 
-      # Test a hook
-      #
-      # Example Request
-      #   GET /hooks/:id
+      desc 'Test a hook'
+      params do
+        requires :id, type: Integer, desc: 'The ID of the system hook'
+      end
       get ":id" do
-        @hook = SystemHook.find(params[:id])
+        hook = SystemHook.find(params[:id])
         data = {
           event_name: "project_create",
           name: "Ruby",
@@ -47,23 +45,21 @@ module API
           owner_name: "Someone",
           owner_email: "example@gitlabhq.com"
         }
-        @hook.execute(data, 'system_hooks')
+        hook.execute(data, 'system_hooks')
         data
       end
 
-      # Delete a hook. This is an idempotent function.
-      #
-      # Parameters:
-      #   id (required) - ID of the hook
-      # Example Request:
-      #   DELETE /hooks/:id
+      desc 'Delete a hook' do
+        success Entities::Hook
+      end
+      params do
+        requires :id, type: Integer, desc: 'The ID of the system hook'
+      end
       delete ":id" do
-        begin
-          @hook = SystemHook.find(params[:id])
-          @hook.destroy
-        rescue
-          # SystemHook raises an Error if no hook with id found
-        end
+        hook = SystemHook.find_by(id: params[:id])
+        not_found!('System hook') unless hook
+
+        present hook.destroy, with: Entities::Hook
       end
     end
   end
diff --git a/lib/api/templates.rb b/lib/api/templates.rb
index b9e718147e1..8a53d9c0095 100644
--- a/lib/api/templates.rb
+++ b/lib/api/templates.rb
@@ -1,39 +1,115 @@
 module API
   class Templates < Grape::API
     GLOBAL_TEMPLATE_TYPES = {
-      gitignores:     Gitlab::Template::GitignoreTemplate,
-      gitlab_ci_ymls: Gitlab::Template::GitlabCiYmlTemplate
+      gitignores: {
+        klass: Gitlab::Template::GitignoreTemplate,
+        gitlab_version: 8.8
+      },
+      gitlab_ci_ymls: {
+        klass: Gitlab::Template::GitlabCiYmlTemplate,
+        gitlab_version: 8.9
+      }
     }.freeze
+    PROJECT_TEMPLATE_REGEX =
+      /[\<\{\[]
+        (project|description|
+        one\sline\s.+\swhat\sit\sdoes\.) # matching the start and end is enough here
+      [\>\}\]]/xi.freeze
+    YEAR_TEMPLATE_REGEX = /[<{\[](year|yyyy)[>}\]]/i.freeze
+    FULLNAME_TEMPLATE_REGEX =
+      /[\<\{\[]
+        (fullname|name\sof\s(author|copyright\sowner))
+      [\>\}\]]/xi.freeze
+    DEPRECATION_MESSAGE = ' This endpoint is deprecated and will be removed in GitLab 9.0.'.freeze
 
     helpers do
+      def parsed_license_template
+        # We create a fresh Licensee::License object since we'll modify its
+        # content in place below.
+        template = Licensee::License.new(params[:name])
+
+        template.content.gsub!(YEAR_TEMPLATE_REGEX, Time.now.year.to_s)
+        template.content.gsub!(PROJECT_TEMPLATE_REGEX, params[:project]) if params[:project].present?
+
+        fullname = params[:fullname].presence || current_user.try(:name)
+        template.content.gsub!(FULLNAME_TEMPLATE_REGEX, fullname) if fullname
+        template
+      end
+
       def render_response(template_type, template)
         not_found!(template_type.to_s.singularize) unless template
         present template, with: Entities::Template
       end
     end
 
-    GLOBAL_TEMPLATE_TYPES.each do |template_type, klass|
-      # Get the list of the available template
-      #
-      # Example Request:
-      #   GET /gitignores
-      #   GET /gitlab_ci_ymls
-      get template_type.to_s do
-        present klass.all, with: Entities::TemplatesList
-      end
-
-      # Get the text for a specific template present in local filesystem
-      #
-      # Parameters:
-      #   name (required) - The name of a template
-      #
-      # Example Request:
-      #   GET /gitignores/Elixir
-      #   GET /gitlab_ci_ymls/Ruby
-      get "#{template_type}/:name" do
-        required_attributes! [:name]
-        new_template = klass.find(params[:name])
-        render_response(template_type, new_template)
+    { "licenses" => :deprecated, "templates/licenses" => :ok }.each do |route, status|
+      desc 'Get the list of the available license template' do
+        detailed_desc = 'This feature was introduced in GitLab 8.7.'
+        detailed_desc << DEPRECATION_MESSAGE unless status == :ok
+        detail detailed_desc
+        success Entities::RepoLicense
+      end
+      params do
+        optional :popular, type: Boolean, desc: 'If passed, returns only popular licenses'
+      end 
+      get route do
+        options = {
+          featured: declared(params).popular.present? ? true : nil
+        }
+        present Licensee::License.all(options), with: Entities::RepoLicense
+      end
+    end
+
+    { "licenses/:name" => :deprecated, "templates/licenses/:name" => :ok }.each do |route, status|
+      desc 'Get the text for a specific license' do
+        detailed_desc = 'This feature was introduced in GitLab 8.7.'
+        detailed_desc << DEPRECATION_MESSAGE unless status == :ok
+        detail detailed_desc
+        success Entities::RepoLicense
+      end
+      params do
+        requires :name, type: String, desc: 'The name of the template'
+      end 
+      get route, requirements: { name: /[\w\.-]+/ } do
+        not_found!('License') unless Licensee::License.find(declared(params).name)
+
+        template = parsed_license_template
+
+        present template, with: Entities::RepoLicense
+      end
+    end
+      
+    GLOBAL_TEMPLATE_TYPES.each do |template_type, properties|
+      klass = properties[:klass]
+      gitlab_version = properties[:gitlab_version]
+
+      { template_type => :deprecated, "templates/#{template_type}" => :ok }.each do |route, status|
+        desc 'Get the list of the available template' do
+          detailed_desc = "This feature was introduced in GitLab #{gitlab_version}."
+          detailed_desc << DEPRECATION_MESSAGE unless status == :ok
+          detail detailed_desc
+          success Entities::TemplatesList
+        end
+        get route do
+          present klass.all, with: Entities::TemplatesList
+        end
+      end
+
+      { "#{template_type}/:name" => :deprecated, "templates/#{template_type}/:name" => :ok }.each do |route, status|
+        desc 'Get the text for a specific template present in local filesystem' do
+          detailed_desc = "This feature was introduced in GitLab #{gitlab_version}."
+          detailed_desc << DEPRECATION_MESSAGE unless status == :ok
+          detail detailed_desc
+          success Entities::Template
+        end
+        params do
+          requires :name, type: String, desc: 'The name of the template'
+        end 
+        get route do
+          new_template = klass.find(declared(params).name)
+
+          render_response(template_type, new_template)
+        end
       end
     end
   end
diff --git a/lib/api/todos.rb b/lib/api/todos.rb
index 19df13d8aac..832b04a3bb1 100644
--- a/lib/api/todos.rb
+++ b/lib/api/todos.rb
@@ -8,18 +8,19 @@ module API
       'issues' => ->(id) { find_project_issue(id) }
     }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
       ISSUABLE_TYPES.each do |type, finder|
         type_id_str = "#{type.singularize}_id".to_sym
 
-        # Create a todo on an issuable
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   issuable_id (required) - The ID of an issuable
-        # Example Request:
-        #   POST /projects/:id/issues/:issuable_id/todo
-        #   POST /projects/:id/merge_requests/:issuable_id/todo
+        desc 'Create a todo on an issuable' do
+          success Entities::Todo
+        end
+        params do
+          requires type_id_str, type: Integer, desc: 'The ID of an issuable'
+        end
         post ":id/#{type}/:#{type_id_str}/todo" do
           issuable = instance_exec(params[type_id_str], &finder)
           todo = TodoService.new.mark_todo(issuable, current_user).first
@@ -40,25 +41,21 @@ module API
         end
       end
 
-      # Get a todo list
-      #
-      # Example Request:
-      #  GET /todos
-      #
+      desc 'Get a todo list' do
+        success Entities::Todo
+      end
       get do
         todos = find_todos
 
         present paginate(todos), with: Entities::Todo, current_user: current_user
       end
 
-      # Mark a todo as done
-      #
-      # Parameters:
-      #   id: (required) - The ID of the todo being marked as done
-      #
-      # Example Request:
-      #  DELETE /todos/:id
-      #
+      desc 'Mark a todo as done' do
+        success Entities::Todo
+      end
+      params do
+        requires :id, type: Integer, desc: 'The ID of the todo being marked as done'
+      end
       delete ':id' do
         todo = current_user.todos.find(params[:id])
         TodoService.new.mark_todos_as_done([todo], current_user)
@@ -66,11 +63,7 @@ module API
         present todo.reload, with: Entities::Todo, current_user: current_user
       end
 
-      # Mark all todos as done
-      #
-      # Example Request:
-      #  DELETE /todos
-      #
+      desc 'Mark all todos as done'
       delete do
         todos = find_todos
         TodoService.new.mark_todos_as_done(todos, current_user)
diff --git a/lib/api/users.rb b/lib/api/users.rb
index 4924182770b..6ab9786a97a 100644
--- a/lib/api/users.rb
+++ b/lib/api/users.rb
@@ -338,6 +338,26 @@ module API
           user.activate
         end
       end
+
+      desc 'Get contribution events of a specified user' do
+        detail 'This feature was introduced in GitLab 8.13.'
+        success Entities::Event
+      end
+      params do
+        requires :id, type: String, desc: 'The user ID'
+      end
+      get ':id/events' do
+        user = User.find_by(id: declared(params).id)
+        not_found!('User') unless user
+
+        events = user.recent_events.
+          merge(ProjectsFinder.new.execute(current_user)).
+          references(:project).
+          with_associations.
+          page(params[:page])
+
+        present paginate(events), with: Entities::Event
+      end
     end
 
     resource :user do
diff --git a/lib/api/variables.rb b/lib/api/variables.rb
index f6495071a11..b9fb3c21dbb 100644
--- a/lib/api/variables.rb
+++ b/lib/api/variables.rb
@@ -4,27 +4,29 @@ module API
     before { authenticate! }
     before { authorize! :admin_build, user_project }
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
+
     resource :projects do
-      # Get project variables
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   page (optional) - The page number for pagination
-      #   per_page (optional) - The value of items per page to show
-      # Example Request:
-      #   GET /projects/:id/variables
+      desc 'Get project variables' do
+        success Entities::Variable
+      end
+      params do
+        optional :page, type: Integer, desc: 'The page number for pagination'
+        optional :per_page, type: Integer, desc: 'The value of items per page to show'
+      end
       get ':id/variables' do
         variables = user_project.variables
         present paginate(variables), with: Entities::Variable
       end
 
-      # Get specific variable of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   key (required) - The `key` of variable
-      # Example Request:
-      #   GET /projects/:id/variables/:key
+      desc 'Get a specific variable from a project' do
+        success Entities::Variable
+      end
+      params do
+        requires :key, type: String, desc: 'The key of the variable'
+      end
       get ':id/variables/:key' do
         key = params[:key]
         variable = user_project.variables.find_by(key: key.to_s)
@@ -34,18 +36,15 @@ module API
         present variable, with: Entities::Variable
       end
 
-      # Create a new variable in project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   key (required) - The key of variable
-      #   value (required) - The value of variable
-      # Example Request:
-      #   POST /projects/:id/variables
+      desc 'Create a new variable in a project' do
+        success Entities::Variable
+      end
+      params do
+        requires :key, type: String, desc: 'The key of the variable'
+        requires :value, type: String, desc: 'The value of the variable'
+      end
       post ':id/variables' do
-        required_attributes! [:key, :value]
-
-        variable = user_project.variables.create(key: params[:key], value: params[:value])
+        variable = user_project.variables.create(declared(params, include_parent_namespaces: false).to_h)
 
         if variable.valid?
           present variable, with: Entities::Variable
@@ -54,41 +53,37 @@ module API
         end
       end
 
-      # Update existing variable of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   key (optional) - The `key` of variable
-      #   value (optional) - New value for `value` field of variable
-      # Example Request:
-      #   PUT /projects/:id/variables/:key
+      desc 'Update an existing variable from a project' do
+        success Entities::Variable
+      end
+      params do
+        optional :key, type: String, desc: 'The key of the variable'
+        optional :value, type: String, desc: 'The value of the variable'
+      end
       put ':id/variables/:key' do
-        variable = user_project.variables.find_by(key: params[:key].to_s)
+        variable = user_project.variables.find_by(key: params[:key])
 
         return not_found!('Variable') unless variable
 
-        attrs = attributes_for_keys [:value]
-        if variable.update(attrs)
+        if variable.update(value: params[:value])
           present variable, with: Entities::Variable
         else
           render_validation_error!(variable)
         end
       end
 
-      # Delete existing variable of a project
-      #
-      # Parameters:
-      #   id (required) - The ID of a project
-      #   key (required) - The ID of a variable
-      # Example Request:
-      #   DELETE /projects/:id/variables/:key
+      desc 'Delete an existing variable from a project' do
+        success Entities::Variable
+      end
+      params do
+        requires :key, type: String, desc: 'The key of the variable'
+      end
       delete ':id/variables/:key' do
-        variable = user_project.variables.find_by(key: params[:key].to_s)
+        variable = user_project.variables.find_by(key: params[:key])
 
         return not_found!('Variable') unless variable
-        variable.destroy
 
-        present variable, with: Entities::Variable
+        present variable.destroy, with: Entities::Variable
       end
     end
   end
diff --git a/lib/api/version.rb b/lib/api/version.rb
new file mode 100644
index 00000000000..9ba576bd828
--- /dev/null
+++ b/lib/api/version.rb
@@ -0,0 +1,12 @@
+module API
+  class Version < Grape::API
+    before { authenticate! }
+
+    desc 'Get the version information of the GitLab instance.' do
+      detail 'This feature was introduced in GitLab 8.13.'
+    end
+    get '/version' do
+      { version: Gitlab::VERSION, revision: Gitlab::REVISION }
+    end
+  end
+end