Merge branch 'api-get-tag' into 'master'

API: Ability to retrieve a single tag

* Closes #14330

/cc @dblessing

See merge request !3577

CHANGELOG

@@ -29,6 +29,7 @@ v 8.7.0 (unreleased)
   - Implement 'TODOs View' as an option for dashboard preferences !3379 (Elias W.)
   - Gracefully handle notes on deleted commits in merge requests (Stan Hu)
   - Fix creation of merge requests for orphaned branches (Stan Hu)
+  - API: Ability to retrieve a single tag (Robert Schilling)
   - Fall back to `In-Reply-To` and `References` headers when sub-addressing is not available (David Padilla)
   - Remove "Congratulations!" tweet button on newly-created project. (Connor Shea)
   - Fix admin/projects when using visibility levels on search (PotHix)

doc/api/tags.md

@@ -38,6 +38,50 @@ Parameters:
 ]
 ```
 
+## Get a single repository tag
+
+Get a specific repository tag determined by its name. It returns `200` together
+with the tag information if the tag exists. It returns `404` if the tag does not
+exist.
+
+```
+GET /projects/:id/repository/tags/:tag_name
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer | yes | The ID of a project |
+| `tag_name` | string | yes | The name of the tag |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/tags/v1.0.0
+```
+
+Example Response:
+
+```json
+{
+  "name": "v5.0.0",
+  "message": null,
+  "commit": {
+    "id": "60a8ff033665e1207714d6670fcd7b65304ec02f",
+    "message": "v5.0.0\n",
+    "parent_ids": [
+      "f61c062ff8bcbdb00e0a1b3317a91aed6ceee06b"
+    ],
+    "authored_date": "2015-02-01T21:56:31.000+01:00",
+    "author_name": "Arthur Verschaeve",
+    "author_email": "contact@arthurverschaeve.be",
+    "committed_date": "2015-02-01T21:56:31.000+01:00",
+    "committer_name": "Arthur Verschaeve",
+    "committer_email": "contact@arthurverschaeve.be"
+  },
+  "release": null
+}
+```
+
 ## Create a new tag
 
 Creates a new tag in the repository that points to the supplied ref.

lib/api/tags.rb

@@ -16,6 +16,20 @@ module API
                 with: Entities::RepoTag, project: user_project
       end
 
+      # Get a single repository tag
+      #
+      # Parameters:
+      #   id (required)       - The ID of a project
+      #   tag_name (required) - The name of the tag
+      # Example Request:
+      #   GET /projects/:id/repository/tags/:tag_name
+      get ":id/repository/tags/:tag_name", requirements: { tag_name: /.+/ } do
+        tag = user_project.repository.find_tag(params[:tag_name])
+        not_found!('Tag') unless tag
+
+        present tag, with: Entities::RepoTag, project: user_project
+      end
+
       # Create tag
       #
       # Parameters:

spec/requests/api/tags_spec.rb

@@ -40,6 +40,23 @@ describe API::API, api: true  do
     end
   end
 
+  describe 'GET /projects/:id/repository/tags/:tag_name' do
+    let(:tag_name) { project.repository.tag_names.sort.reverse.first }
+
+    it 'returns a specific tag' do
+      get api("/projects/#{project.id}/repository/tags/#{tag_name}", user)
+
+      expect(response.status).to eq(200)
+      expect(json_response['name']).to eq(tag_name)
+    end
+
+    it 'returns 404 for an invalid tag name' do
+      get api("/projects/#{project.id}/repository/tags/foobar", user)
+
+      expect(response.status).to eq(404)
+    end
+  end
+
   describe 'POST /projects/:id/repository/tags' do
     context 'lightweight tags' do
       it 'should create a new tag' do