boards.go

Documentation: github.com/xanzy/go-gitlab

     1  //
     2  // Copyright 2021, Sander van Harmelen
     3  //
     4  // Licensed under the Apache License, Version 2.0 (the "License");
     5  // you may not use this file except in compliance with the License.
     6  // You may obtain a copy of the License at
     7  //
     8  //     http://www.apache.org/licenses/LICENSE-2.0
     9  //
    10  // Unless required by applicable law or agreed to in writing, software
    11  // distributed under the License is distributed on an "AS IS" BASIS,
    12  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  // See the License for the specific language governing permissions and
    14  // limitations under the License.
    15  //
    16  
    17  package gitlab
    18  
    19  import (
    20  	"fmt"
    21  	"net/http"
    22  )
    23  
    24  // IssueBoardsService handles communication with the issue board related
    25  // methods of the GitLab API.
    26  //
    27  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html
    28  type IssueBoardsService struct {
    29  	client *Client
    30  }
    31  
    32  // IssueBoard represents a GitLab issue board.
    33  //
    34  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html
    35  type IssueBoard struct {
    36  	ID        int        `json:"id"`
    37  	Name      string     `json:"name"`
    38  	Project   *Project   `json:"project"`
    39  	Milestone *Milestone `json:"milestone"`
    40  	Assignee  *struct {
    41  		ID        int    `json:"id"`
    42  		Username  string `json:"username"`
    43  		Name      string `json:"name"`
    44  		State     string `json:"state"`
    45  		AvatarURL string `json:"avatar_url"`
    46  		WebURL    string `json:"web_url"`
    47  	} `json:"assignee"`
    48  	Lists  []*BoardList    `json:"lists"`
    49  	Weight int             `json:"weight"`
    50  	Labels []*LabelDetails `json:"labels"`
    51  }
    52  
    53  func (b IssueBoard) String() string {
    54  	return Stringify(b)
    55  }
    56  
    57  // BoardList represents a GitLab board list.
    58  //
    59  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html
    60  type BoardList struct {
    61  	ID       int `json:"id"`
    62  	Assignee *struct {
    63  		ID       int    `json:"id"`
    64  		Name     string `json:"name"`
    65  		Username string `json:"username"`
    66  	} `json:"assignee"`
    67  	Iteration      *ProjectIteration `json:"iteration"`
    68  	Label          *Label            `json:"label"`
    69  	MaxIssueCount  int               `json:"max_issue_count"`
    70  	MaxIssueWeight int               `json:"max_issue_weight"`
    71  	Milestone      *Milestone        `json:"milestone"`
    72  	Position       int               `json:"position"`
    73  }
    74  
    75  func (b BoardList) String() string {
    76  	return Stringify(b)
    77  }
    78  
    79  // CreateIssueBoardOptions represents the available CreateIssueBoard() options.
    80  //
    81  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#create-an-issue-board
    82  type CreateIssueBoardOptions struct {
    83  	Name *string `url:"name,omitempty" json:"name,omitempty"`
    84  }
    85  
    86  // CreateIssueBoard creates a new issue board.
    87  //
    88  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#create-an-issue-board
    89  func (s *IssueBoardsService) CreateIssueBoard(pid interface{}, opt *CreateIssueBoardOptions, options ...RequestOptionFunc) (*IssueBoard, *Response, error) {
    90  	project, err := parseID(pid)
    91  	if err != nil {
    92  		return nil, nil, err
    93  	}
    94  	u := fmt.Sprintf("projects/%s/boards", PathEscape(project))
    95  
    96  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
    97  	if err != nil {
    98  		return nil, nil, err
    99  	}
   100  
   101  	board := new(IssueBoard)
   102  	resp, err := s.client.Do(req, board)
   103  	if err != nil {
   104  		return nil, resp, err
   105  	}
   106  
   107  	return board, resp, nil
   108  }
   109  
   110  // UpdateIssueBoardOptions represents the available UpdateIssueBoard() options.
   111  //
   112  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#update-an-issue-board
   113  type UpdateIssueBoardOptions struct {
   114  	Name        *string       `url:"name,omitempty" json:"name,omitempty"`
   115  	AssigneeID  *int          `url:"assignee_id,omitempty" json:"assignee_id,omitempty"`
   116  	MilestoneID *int          `url:"milestone_id,omitempty" json:"milestone_id,omitempty"`
   117  	Labels      *LabelOptions `url:"labels,omitempty" json:"labels,omitempty"`
   118  	Weight      *int          `url:"weight,omitempty" json:"weight,omitempty"`
   119  }
   120  
   121  // UpdateIssueBoard update an issue board.
   122  //
   123  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#update-an-issue-board
   124  func (s *IssueBoardsService) UpdateIssueBoard(pid interface{}, board int, opt *UpdateIssueBoardOptions, options ...RequestOptionFunc) (*IssueBoard, *Response, error) {
   125  	project, err := parseID(pid)
   126  	if err != nil {
   127  		return nil, nil, err
   128  	}
   129  	u := fmt.Sprintf("projects/%s/boards/%d", PathEscape(project), board)
   130  
   131  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   132  	if err != nil {
   133  		return nil, nil, err
   134  	}
   135  
   136  	is := new(IssueBoard)
   137  	resp, err := s.client.Do(req, is)
   138  	if err != nil {
   139  		return nil, resp, err
   140  	}
   141  
   142  	return is, resp, nil
   143  }
   144  
   145  // DeleteIssueBoard deletes an issue board.
   146  //
   147  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#delete-an-issue-board
   148  func (s *IssueBoardsService) DeleteIssueBoard(pid interface{}, board int, options ...RequestOptionFunc) (*Response, error) {
   149  	project, err := parseID(pid)
   150  	if err != nil {
   151  		return nil, err
   152  	}
   153  	u := fmt.Sprintf("projects/%s/boards/%d", PathEscape(project), board)
   154  
   155  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   156  	if err != nil {
   157  		return nil, err
   158  	}
   159  
   160  	return s.client.Do(req, nil)
   161  }
   162  
   163  // ListIssueBoardsOptions represents the available ListIssueBoards() options.
   164  //
   165  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#list-project-issue-boards
   166  type ListIssueBoardsOptions ListOptions
   167  
   168  // ListIssueBoards gets a list of all issue boards in a project.
   169  //
   170  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#list-project-issue-boards
   171  func (s *IssueBoardsService) ListIssueBoards(pid interface{}, opt *ListIssueBoardsOptions, options ...RequestOptionFunc) ([]*IssueBoard, *Response, error) {
   172  	project, err := parseID(pid)
   173  	if err != nil {
   174  		return nil, nil, err
   175  	}
   176  	u := fmt.Sprintf("projects/%s/boards", PathEscape(project))
   177  
   178  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   179  	if err != nil {
   180  		return nil, nil, err
   181  	}
   182  
   183  	var is []*IssueBoard
   184  	resp, err := s.client.Do(req, &is)
   185  	if err != nil {
   186  		return nil, resp, err
   187  	}
   188  
   189  	return is, resp, nil
   190  }
   191  
   192  // GetIssueBoard gets a single issue board of a project.
   193  //
   194  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#show-a-single-issue-board
   195  func (s *IssueBoardsService) GetIssueBoard(pid interface{}, board int, options ...RequestOptionFunc) (*IssueBoard, *Response, error) {
   196  	project, err := parseID(pid)
   197  	if err != nil {
   198  		return nil, nil, err
   199  	}
   200  	u := fmt.Sprintf("projects/%s/boards/%d", PathEscape(project), board)
   201  
   202  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   203  	if err != nil {
   204  		return nil, nil, err
   205  	}
   206  
   207  	ib := new(IssueBoard)
   208  	resp, err := s.client.Do(req, ib)
   209  	if err != nil {
   210  		return nil, resp, err
   211  	}
   212  
   213  	return ib, resp, nil
   214  }
   215  
   216  // GetIssueBoardListsOptions represents the available GetIssueBoardLists() options.
   217  //
   218  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#list-board-lists-in-a-project-issue-board
   219  type GetIssueBoardListsOptions ListOptions
   220  
   221  // GetIssueBoardLists gets a list of the issue board's lists. Does not include
   222  // backlog and closed lists.
   223  //
   224  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#list-board-lists-in-a-project-issue-board
   225  func (s *IssueBoardsService) GetIssueBoardLists(pid interface{}, board int, opt *GetIssueBoardListsOptions, options ...RequestOptionFunc) ([]*BoardList, *Response, error) {
   226  	project, err := parseID(pid)
   227  	if err != nil {
   228  		return nil, nil, err
   229  	}
   230  	u := fmt.Sprintf("projects/%s/boards/%d/lists", PathEscape(project), board)
   231  
   232  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   233  	if err != nil {
   234  		return nil, nil, err
   235  	}
   236  
   237  	var bl []*BoardList
   238  	resp, err := s.client.Do(req, &bl)
   239  	if err != nil {
   240  		return nil, resp, err
   241  	}
   242  
   243  	return bl, resp, nil
   244  }
   245  
   246  // GetIssueBoardList gets a single issue board list.
   247  //
   248  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#show-a-single-board-list
   249  func (s *IssueBoardsService) GetIssueBoardList(pid interface{}, board, list int, options ...RequestOptionFunc) (*BoardList, *Response, error) {
   250  	project, err := parseID(pid)
   251  	if err != nil {
   252  		return nil, nil, err
   253  	}
   254  	u := fmt.Sprintf("projects/%s/boards/%d/lists/%d",
   255  		PathEscape(project),
   256  		board,
   257  		list,
   258  	)
   259  
   260  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   261  	if err != nil {
   262  		return nil, nil, err
   263  	}
   264  
   265  	bl := new(BoardList)
   266  	resp, err := s.client.Do(req, bl)
   267  	if err != nil {
   268  		return nil, resp, err
   269  	}
   270  
   271  	return bl, resp, nil
   272  }
   273  
   274  // CreateIssueBoardListOptions represents the available CreateIssueBoardList()
   275  // options.
   276  //
   277  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#create-a-board-list
   278  type CreateIssueBoardListOptions struct {
   279  	LabelID     *int `url:"label_id,omitempty" json:"label_id,omitempty"`
   280  	AssigneeID  *int `url:"assignee_id,omitempty" json:"assignee_id,omitempty"`
   281  	MilestoneID *int `url:"milestone_id,omitempty" json:"milestone_id,omitempty"`
   282  	IterationID *int `url:"iteration_id,omitempty" json:"iteration_id,omitempty"`
   283  }
   284  
   285  // CreateIssueBoardList creates a new issue board list.
   286  //
   287  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#create-a-board-list
   288  func (s *IssueBoardsService) CreateIssueBoardList(pid interface{}, board int, opt *CreateIssueBoardListOptions, options ...RequestOptionFunc) (*BoardList, *Response, error) {
   289  	project, err := parseID(pid)
   290  	if err != nil {
   291  		return nil, nil, err
   292  	}
   293  	u := fmt.Sprintf("projects/%s/boards/%d/lists", PathEscape(project), board)
   294  
   295  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   296  	if err != nil {
   297  		return nil, nil, err
   298  	}
   299  
   300  	bl := new(BoardList)
   301  	resp, err := s.client.Do(req, bl)
   302  	if err != nil {
   303  		return nil, resp, err
   304  	}
   305  
   306  	return bl, resp, nil
   307  }
   308  
   309  // UpdateIssueBoardListOptions represents the available UpdateIssueBoardList()
   310  // options.
   311  //
   312  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#reorder-a-list-in-a-board
   313  type UpdateIssueBoardListOptions struct {
   314  	Position *int `url:"position" json:"position"`
   315  }
   316  
   317  // UpdateIssueBoardList updates the position of an existing issue board list.
   318  //
   319  // GitLab API docs: https://docs.gitlab.com/ee/api/boards.html#reorder-a-list-in-a-board
   320  func (s *IssueBoardsService) UpdateIssueBoardList(pid interface{}, board, list int, opt *UpdateIssueBoardListOptions, options ...RequestOptionFunc) (*BoardList, *Response, error) {
   321  	project, err := parseID(pid)
   322  	if err != nil {
   323  		return nil, nil, err
   324  	}
   325  	u := fmt.Sprintf("projects/%s/boards/%d/lists/%d",
   326  		PathEscape(project),
   327  		board,
   328  		list,
   329  	)
   330  
   331  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   332  	if err != nil {
   333  		return nil, nil, err
   334  	}
   335  
   336  	bl := new(BoardList)
   337  	resp, err := s.client.Do(req, bl)
   338  	if err != nil {
   339  		return nil, resp, err
   340  	}
   341  
   342  	return bl, resp, nil
   343  }
   344  
   345  // DeleteIssueBoardList soft deletes an issue board list. Only for admins and
   346  // project owners.
   347  //
   348  // GitLab API docs:
   349  // https://docs.gitlab.com/ee/api/boards.html#delete-a-board-list-from-a-board
   350  func (s *IssueBoardsService) DeleteIssueBoardList(pid interface{}, board, list int, options ...RequestOptionFunc) (*Response, error) {
   351  	project, err := parseID(pid)
   352  	if err != nil {
   353  		return nil, err
   354  	}
   355  	u := fmt.Sprintf("projects/%s/boards/%d/lists/%d",
   356  		PathEscape(project),
   357  		board,
   358  		list,
   359  	)
   360  
   361  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   362  	if err != nil {
   363  		return nil, err
   364  	}
   365  
   366  	return s.client.Do(req, nil)
   367  }
   368
View as plain text