youtrack

README

YouTrack for Go

Bare bones YouTrack REST API client library for Go that provides authentication using Permanent Token Authorization.

The youtrack.Api type provides methods for making authenticated HTTP GET and POST requests to the YouTrack REST API.

There are also some convenience functions for creating issues.

Contributions welcome.

Testing

The tests communicate with an actual YouTrack endpoint and therefore need credentials to run. You can set these with the YOUTRACK_URL and YOUTRACK_TOKEN environment variables. The YouTrack project must have at least one project with the ID (aka issue prefix or shortName) of TP.

To debug HTTP requests, run:

go test -v -yt-trace

WARNING: -yt-trace logs the entire HTTP request, including Authorization token, so take care when using it or sharing any logs generated from it.

Documentation

Overview

Package youtrack implements REST API client that can be used with YouTrack as described in https://www.jetbrains.com/help/youtrack/incloud/Resources-for-Developers.html

Index

• Variables
• func IssueURL(baseURL *url.URL, shortProjectName string, issueNumberInProject int) *url.URL
• type Api
  • func NewDefaultApi() (*Api, error)
  • func (api *Api) CreateIssue(ctx context.Context, project, summary, description string) (*IssueResult, error)
  • func (api *Api) CreateIssueAttachment(ctx context.Context, issueID string, attachment io.Reader, ...) (string, error)
  • func (api *Api) DoRequest(ctx context.Context, resource *url.URL, method string, ...) error
  • func (api *Api) Get(ctx context.Context, resource *url.URL, jsonResult interface{}) error
  • func (api *Api) IssueURL(shortProjectName string, issueNumberInProject int) *url.URL
  • func (api *Api) ListProjects(ctx context.Context) ([]Project, error)
  • func (api *Api) Post(ctx context.Context, resource *url.URL, jsonRequest, jsonResult interface{}) error
  • func (api *Api) ProjectIDForShortName(ctx context.Context, shortName string) (string, error)
• type IDResult
• type Issue
• type IssueAttachment
• type IssueResult
• type Project
• type ProjectID

Variables

var NotFoundError = errors.New("Not Found")

Functions

func IssueURL

func IssueURL(baseURL *url.URL, shortProjectName string, issueNumberInProject int) *url.URL

IssueURL returns a user facing (rather than REST API) URL to the issue. Note that because this issue uses the short project name in the URL, the link could be broken if the project short name changes.

Types

type Api

type Api struct {
	// BaseURL is the URL to the REST API endpoint for a YouTrack Project. It should
	// end is a slash. For example: https://goyt.myjetbrains.com/youtrack/api/
	BaseURL *url.URL

	// Token is the permanent token used to make authenticated requests.
	// For more information, see:
	// https://www.jetbrains.com/help/youtrack/incloud/authentication-with-permanent-token.html
	Token string

	// EnableTracing turns on extra logging, including HTTP request/response logging.
	// NOTE that the authorization token will be logged when this is enabled.
	EnableTracing bool
}

Api is the YouTrack API context. BaseURL and Token must be set.

func NewDefaultApi

func NewDefaultApi() (*Api, error)

NewDefaultApi returns a new API using a baseURL and permanent authorization token from either flags or environment.

func (*Api) CreateIssue

func (api *Api) CreateIssue(ctx context.Context, project, summary, description string) (*IssueResult, error)

CreateIssue returns the issue ID on success.

func (*Api) CreateIssueAttachment

func (api *Api) CreateIssueAttachment(ctx context.Context, issueID string, attachment io.Reader, name, mediaType string) (string, error)

CreateIssueAttachment attached a file to the given issue ID. On success, the attachment ID is returned.

func (*Api) DoRequest

func (api *Api) DoRequest(ctx context.Context, resource *url.URL, method string, jsonRequest, jsonResult interface{}) error

DoRequest makes an authenticated HTTP request to the YouTrack API. jsonRequest and jsonResult are both optional, and depend on the request being made. A GET request, for example, should probably set jsonRequestBody to nil.

func (*Api) Get

func (api *Api) Get(ctx context.Context, resource *url.URL, jsonResult interface{}) error

Get makes an authenticated GET request to the YouTrack API.

func (*Api) IssueURL

func (api *Api) IssueURL(shortProjectName string, issueNumberInProject int) *url.URL

func (*Api) ListProjects

func (api *Api) ListProjects(ctx context.Context) ([]Project, error)

ListProjects returns a list of Projects the user has access to. For more information, see https://www.jetbrains.com/help/youtrack/incloud/2019.3/resource-api-admin-projects.html

func (*Api) Post

func (api *Api) Post(ctx context.Context, resource *url.URL, jsonRequest, jsonResult interface{}) error

Post makes an authenticated POST request to the YouTrack API.

func (*Api) ProjectIDForShortName

func (api *Api) ProjectIDForShortName(ctx context.Context, shortName string) (string, error)

Return the Project ID for the shortName (issue ID prefix in the YouTrack web UI)

type IDResult

type IDResult struct {
	ID string `json:"id"`
}

type Issue

type Issue struct {
	Summary     string    `json:"summary"`
	Description string    `json:"description"`
	Project     ProjectID `json:"project"`
}

type IssueAttachment

type IssueAttachment struct {
	Name          string `json:"name"`
	Base64Content string `json:"base64Content"`
}

type IssueResult

type IssueResult struct {
	IDResult
	NumberInProject int `json:"numberInProject"`
}

type Project

type Project struct {
	ID        string `json:"id"`
	ShortName string `json:"shortName"`
}

type ProjectID

type ProjectID struct {
	ID string `json:"id"`
}