topics.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  	"encoding/json"
    21  	"fmt"
    22  	"io"
    23  	"net/http"
    24  
    25  	retryablehttp "github.com/hashicorp/go-retryablehttp"
    26  )
    27  
    28  // TopicsService handles communication with the topics related methods
    29  // of the GitLab API.
    30  //
    31  // GitLab API docs: https://docs.gitlab.com/ee/api/topics.html
    32  type TopicsService struct {
    33  	client *Client
    34  }
    35  
    36  // Topic represents a GitLab project topic.
    37  //
    38  // GitLab API docs: https://docs.gitlab.com/ee/api/topics.html
    39  type Topic struct {
    40  	ID                 int    `json:"id"`
    41  	Name               string `json:"name"`
    42  	Title              string `json:"title"`
    43  	Description        string `json:"description"`
    44  	TotalProjectsCount uint64 `json:"total_projects_count"`
    45  	AvatarURL          string `json:"avatar_url"`
    46  }
    47  
    48  func (t Topic) String() string {
    49  	return Stringify(t)
    50  }
    51  
    52  // ListTopicsOptions represents the available ListTopics() options.
    53  //
    54  // GitLab API docs: https://docs.gitlab.com/ee/api/topics.html#list-topics
    55  type ListTopicsOptions struct {
    56  	ListOptions
    57  	Search *string `url:"search,omitempty" json:"search,omitempty"`
    58  }
    59  
    60  // ListTopics returns a list of project topics in the GitLab instance ordered
    61  // by number of associated projects.
    62  //
    63  // GitLab API docs: https://docs.gitlab.com/ee/api/topics.html#list-topics
    64  func (s *TopicsService) ListTopics(opt *ListTopicsOptions, options ...RequestOptionFunc) ([]*Topic, *Response, error) {
    65  	req, err := s.client.NewRequest(http.MethodGet, "topics", opt, options)
    66  	if err != nil {
    67  		return nil, nil, err
    68  	}
    69  
    70  	var t []*Topic
    71  	resp, err := s.client.Do(req, &t)
    72  	if err != nil {
    73  		return nil, resp, err
    74  	}
    75  
    76  	return t, resp, nil
    77  }
    78  
    79  // GetTopic gets a project topic by ID.
    80  //
    81  // GitLab API docs: https://docs.gitlab.com/ee/api/topics.html#get-a-topic
    82  func (s *TopicsService) GetTopic(topic int, options ...RequestOptionFunc) (*Topic, *Response, error) {
    83  	u := fmt.Sprintf("topics/%d", topic)
    84  
    85  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
    86  	if err != nil {
    87  		return nil, nil, err
    88  	}
    89  
    90  	t := new(Topic)
    91  	resp, err := s.client.Do(req, t)
    92  	if err != nil {
    93  		return nil, resp, err
    94  	}
    95  
    96  	return t, resp, nil
    97  }
    98  
    99  // CreateTopicOptions represents the available CreateTopic() options.
   100  //
   101  // GitLab API docs:
   102  // https://docs.gitlab.com/ee/api/topics.html#create-a-project-topic
   103  type CreateTopicOptions struct {
   104  	Name        *string      `url:"name,omitempty" json:"name,omitempty"`
   105  	Title       *string      `url:"title,omitempty" json:"title,omitempty"`
   106  	Description *string      `url:"description,omitempty" json:"description,omitempty"`
   107  	Avatar      *TopicAvatar `url:"-" json:"-"`
   108  }
   109  
   110  // TopicAvatar represents a GitLab topic avatar.
   111  type TopicAvatar struct {
   112  	Filename string
   113  	Image    io.Reader
   114  }
   115  
   116  // MarshalJSON implements the json.Marshaler interface.
   117  func (a *TopicAvatar) MarshalJSON() ([]byte, error) {
   118  	if a.Filename == "" && a.Image == nil {
   119  		return []byte(`""`), nil
   120  	}
   121  	type alias TopicAvatar
   122  	return json.Marshal((*alias)(a))
   123  }
   124  
   125  // CreateTopic creates a new project topic.
   126  //
   127  // GitLab API docs:
   128  // https://docs.gitlab.com/ee/api/topics.html#create-a-project-topic
   129  func (s *TopicsService) CreateTopic(opt *CreateTopicOptions, options ...RequestOptionFunc) (*Topic, *Response, error) {
   130  	var err error
   131  	var req *retryablehttp.Request
   132  
   133  	if opt.Avatar == nil {
   134  		req, err = s.client.NewRequest(http.MethodPost, "topics", opt, options)
   135  	} else {
   136  		req, err = s.client.UploadRequest(
   137  			http.MethodPost,
   138  			"topics",
   139  			opt.Avatar.Image,
   140  			opt.Avatar.Filename,
   141  			UploadAvatar,
   142  			opt,
   143  			options,
   144  		)
   145  	}
   146  	if err != nil {
   147  		return nil, nil, err
   148  	}
   149  
   150  	t := new(Topic)
   151  	resp, err := s.client.Do(req, t)
   152  	if err != nil {
   153  		return nil, resp, err
   154  	}
   155  
   156  	return t, resp, nil
   157  }
   158  
   159  // UpdateTopicOptions represents the available UpdateTopic() options.
   160  //
   161  // GitLab API docs:
   162  // https://docs.gitlab.com/ee/api/topics.html#update-a-project-topic
   163  type UpdateTopicOptions struct {
   164  	Name        *string      `url:"name,omitempty" json:"name,omitempty"`
   165  	Title       *string      `url:"title,omitempty" json:"title,omitempty"`
   166  	Description *string      `url:"description,omitempty" json:"description,omitempty"`
   167  	Avatar      *TopicAvatar `url:"-" json:"avatar,omitempty"`
   168  }
   169  
   170  // UpdateTopic updates a project topic. Only available to administrators.
   171  //
   172  // To remove a topic avatar set the TopicAvatar.Filename to an empty string
   173  // and set TopicAvatar.Image to nil.
   174  //
   175  // GitLab API docs:
   176  // https://docs.gitlab.com/ee/api/topics.html#update-a-project-topic
   177  func (s *TopicsService) UpdateTopic(topic int, opt *UpdateTopicOptions, options ...RequestOptionFunc) (*Topic, *Response, error) {
   178  	u := fmt.Sprintf("topics/%d", topic)
   179  
   180  	var err error
   181  	var req *retryablehttp.Request
   182  
   183  	if opt.Avatar == nil || (opt.Avatar.Filename == "" && opt.Avatar.Image == nil) {
   184  		req, err = s.client.NewRequest(http.MethodPut, u, opt, options)
   185  	} else {
   186  		req, err = s.client.UploadRequest(
   187  			http.MethodPut,
   188  			u,
   189  			opt.Avatar.Image,
   190  			opt.Avatar.Filename,
   191  			UploadAvatar,
   192  			opt,
   193  			options,
   194  		)
   195  	}
   196  	if err != nil {
   197  		return nil, nil, err
   198  	}
   199  
   200  	t := new(Topic)
   201  	resp, err := s.client.Do(req, t)
   202  	if err != nil {
   203  		return nil, resp, err
   204  	}
   205  
   206  	return t, resp, nil
   207  }
   208  
   209  // DeleteTopic deletes a project topic. Only available to administrators.
   210  //
   211  // GitLab API docs:
   212  // https://docs.gitlab.com/ee/api/topics.html#delete-a-project-topic
   213  func (s *TopicsService) DeleteTopic(topic int, options ...RequestOptionFunc) (*Response, error) {
   214  	u := fmt.Sprintf("topics/%d", topic)
   215  
   216  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   217  	if err != nil {
   218  		return nil, err
   219  	}
   220  
   221  	return s.client.Do(req, nil)
   222  }
   223
View as plain text