Feature #23894

Expose repository through REST API

Added by Daniel Dehennin about 1 year ago. Updated 10 months ago.

Status:NewStart date:
Priority:NormalDue date:
Assignee:-% Done:

0%

Category:REST API
Target version:-
Resolution:

Description

Hello,

The public REST API does not contains information about repository.

It seems that the only way to access repository information is through the repository WS, but there is only one key.

I would like to have repository information per project, like what I get with GET /sys/projects.xml?key=<WS KEY>.

We may only list repositories when adding an ?include=repositories:

  • for all projects GET /projects.json?include=repositories
    {
       "projects" : [
          {
             "identifier" : "project",
             "id" : 1,
             "name" : "Project Name",
         [...]
             "repositories" : [
                {
                   "id" : 1,
                   "identifier" : "",
                   "is_default" : true,
                   "type" : "Repository::Git",
                   "url" : "repositories/project-repo.git" 
                }
             ]
          }
       ],
       "limit" : 25,
       "total_count" : 1,
       "offset" : 0
    }
    
  • per project GET /projects/1.json?include=repositories
    {
       "project" : {
          "id" : 1,
          "identifier" : "project",
          "name" : "Project Name",
          "repositories" : [
             {
                "id" : 1,
                "identifier" : "",
                "is_default" : true,
                "url" : "repositories/project-repo.git",
                "type" : "Repository::Git" 
             }
          ]
       }
    }
    

Regards.

Include-repositories-in-projects-API.patch Magnifier (1.07 KB) Daniel Dehennin, 2016-09-26 14:30

0001-Planio-Add-a-read-only-API-for-repositories.patch Magnifier (4.99 KB) Holger Just, 2016-09-26 16:17


Related issues

Related to Redmine - Feature #11977: REST API for repositories New

History

#1 Updated by Daniel Dehennin about 1 year ago

I made a patch to include the repositories in projects API.

I'll work on adding a complete CRUD with two routes

  • per project under /projects/:id/repositories
  • global under /repositories

The patch was made against the Git repository.

#2 Updated by Holger Just about 1 year ago

As an alternative to the proposed patch by Daniel (or maybe in addition to it), we at Planio have already rolled out a read-only API for repositories related to #11977 which we provide in the attached patch. Unfortunately, we haven't managed to provide the patch earlier :(

You can call the API as http://redmine.example.com/repositories.json. It supports the following optional parameters:

  • scm: The type of repositories that should be shown. We support any of the registered repository types here. If no scm is given or the type is unknown, we show all repositories visible to the current user.
  • include: fetch associated data (optional, use comma to fetch multiple associations). Possible values:
    • branches: Include known branches of the repository. This is only useful if the repository type knows the concept of branches like git or mercurial.

In the API response, we deliberately do not include the repository URL that is configured in Redmine. The reason for that is that most of the time, this URL won't be the one visible to clients. Instead, this is often a file system path (mandatory for at least git and mercurial) or an internal URL in the case of SVN. Instead, we offer an extension point for repository hosting plugins to easily add information they deem useful. This data can be fetched from the respective configuration of the plugin. Alternatively, an administrator setting up their internal Redmine with tools like Redmine.pm can easily write a very simple plugin which hooks into the API to provide this information. This could look like this:

Redmine::Plugin.register :redmine_my_repositories do
  name 'My Repositories'
  author 'John Doe'
  description 'Add custom repository information to the API'
  version '1.0.0'
end

module MyRepositories
  class ApiHooks < Redmine::Hook::Listener
    def api_repositories_index(context)
      render_repository_urls(context[:api], context[:repository])
    end

    private

    def render_repository_urls(api, repository)
      if repository.is_a? Repository::Subversion
        api.svn_url "https://#{Setting.hostname}/svn/#{[repository.project.identifier, repository.identifier].compact.join('/')}
      elsif repository.is_a? Repository::Git
        api.git_url "git@#{Setting.hostname}:#{[repository.project.identifier, repository.identifier].compact.join('/')}
      end
    end
  end
end

If you intend to use both patches, the supplied data should be adapted so that both APIs provide similar data.

#3 Updated by Daniel Dehennin about 1 year ago

Holger Just wrote:

As an alternative to the proposed patch by Daniel (or maybe in addition to it), we at Planio have already rolled out a read-only API for repositories related to #11977 which we provide in the attached patch. Unfortunately, we haven't managed to provide the patch earlier :(

Thanks, that's part of what I wanted to do, I'll include your patch in a branch of my Git and extend it to be a simple CRUD.

In the API response, we deliberately do not include the repository URL that is configured in Redmine. The reason for that is that most of the time, this URL won't be the one visible to clients. Instead, this is often a file system path (mandatory for at least git and mercurial) or an internal URL in the case of SVN. Instead, we offer an extension point for repository hosting plugins to easily add information they deem useful. This data can be fetched from the respective configuration of the plugin. Alternatively, an administrator setting up their internal Redmine with tools like Redmine.pm can easily write a very simple plugin which hooks into the API to provide this information. This could look like this:

[...]

If you intend to use both patches, the supplied data should be adapted so that both APIs provide similar data.

I agree, the :url is not very useful, I'm wondering about using it for a list of clone URLs but not all SCM support it.

Regards.

#4 Updated by Toshi MARUYAMA about 1 year ago

  • Category set to REST API

#5 Updated by Toshi MARUYAMA about 1 year ago

Also available in: Atom PDF