Documentation

Overview

Package api contains Go client and types for the GopherPit API.

For more information about the Engine API, see the documentation: https://gopherpit.com/docs/api

Authorization is performed by Personal Access Token which can be obtained on Settings page of the GopherPit site.

Usage

Communication with the API is performed by creating a Client object and calling methods on it.

Example:

package main

import (
    "fmt"
    "os"

    "gopherpit.com/gopherpit/api"
)

func main() {
    c := api.NewClient(os.Getenv("GOPHERPIT_TOKEN"))

    domains, err := c.Domains("", 0)
    if err != nil {
        fmt.Fprintln(os.Stderr, "get domains", err)
        os.Exit(1)
    }

    for _, domain := range domains.Domains {
        fmt.Printf("%s %s\n", domain.ID, domain.FQDN)
    }
}

To use GopherPit installation on-premises:

c := api.NewClientWithEndpoint("https://go.example.com/api/v1", "TOKEN")

Index

Constants

View Source
const MaxLimit = 100

    MaxLimit is a default maximum number of elements for paged responses.

    Variables

    View Source
    var (
    	ErrBadRequest                    = errorRegistry.MustAddMessageError(400, "Bad Request")
    	ErrUnauthorized                  = errorRegistry.MustAddMessageError(401, "Unauthorized")
    	ErrForbidden                     = errorRegistry.MustAddMessageError(403, "Forbidden")
    	ErrNotFound                      = errorRegistry.MustAddMessageError(404, "Not Found")
    	ErrTooManyRequests               = errorRegistry.MustAddMessageError(429, "Too Many Requests")
    	ErrInternalServerError           = errorRegistry.MustAddMessageError(500, "Internal Server Error")
    	ErrMaintenance                   = errorRegistry.MustAddMessageError(503, "Maintenance")
    	ErrDomainNotFound                = errorRegistry.MustAddMessageError(1000, "Domain Not Found")
    	ErrDomainAlreadyExists           = errorRegistry.MustAddMessageError(1001, "Domain Already Exists")
    	ErrDomainFQDNRequired            = errorRegistry.MustAddMessageError(1010, "Domain FQDN Required")
    	ErrDomainFQDNInvalid             = errorRegistry.MustAddMessageError(1011, "Domain FQDN Invalid")
    	ErrDomainNotAvailable            = errorRegistry.MustAddMessageError(1012, "Domain Not Available")
    	ErrDomainWithTooManySubdomains   = errorRegistry.MustAddMessageError(1013, "Domain With Too Many Subdomains")
    	ErrDomainNeedsVerification       = errorRegistry.MustAddMessageError(1014, "Domain Needs Verification")
    	ErrUserDoesNotExist              = errorRegistry.MustAddMessageError(1100, "User Does Not Exist")
    	ErrUserAlreadyGranted            = errorRegistry.MustAddMessageError(1101, "User Already Granted")
    	ErrUserNotGranted                = errorRegistry.MustAddMessageError(1102, "User Not Granted")
    	ErrPackageNotFound               = errorRegistry.MustAddMessageError(2000, "Package Not Found")
    	ErrPackageAlreadyExists          = errorRegistry.MustAddMessageError(2001, "Package Already Exists")
    	ErrPackageDomainRequired         = errorRegistry.MustAddMessageError(2010, "Package Domain Required")
    	ErrPackagePathRequired           = errorRegistry.MustAddMessageError(2020, "Package Path Required")
    	ErrPackageVCSRequired            = errorRegistry.MustAddMessageError(2030, "Package VCS Required")
    	ErrPackageRepoRootRequired       = errorRegistry.MustAddMessageError(2040, "Package Repository Root Required")
    	ErrPackageRepoRootInvalid        = errorRegistry.MustAddMessageError(2041, "Package Repository Root Invalid")
    	ErrPackageRepoRootSchemeRequired = errorRegistry.MustAddMessageError(2042, "Package Repository Root Scheme Required")
    	ErrPackageRepoRootSchemeInvalid  = errorRegistry.MustAddMessageError(2043, "Package Repository Root Scheme Invalid")
    	ErrPackageRepoRootHostInvalid    = errorRegistry.MustAddMessageError(2044, "Package Repository Root Host Invalid")
    	ErrPackageRefTypeInvalid         = errorRegistry.MustAddMessageError(2050, "Package Reference Type Invalid")
    	ErrPackageRefNameRequired        = errorRegistry.MustAddMessageError(2060, "Package Reference Name Required")
    	ErrPackageRefChangeRejected      = errorRegistry.MustAddMessageError(2070, "Package Reference Change Rejected")
    	ErrPackageRedirectURLInvalid     = errorRegistry.MustAddMessageError(2080, "Package Redirect URL Invalid")
    )

      Errors that the API can return.

      Functions

      This section is empty.

      Types

      type Client

      type Client struct {
      	apiClient.Client
      }

        Client is the API client that performs all operations against GopherPit server.

        func NewClient

        func NewClient(key string) *Client

          NewClient creates a new Client object with gopherpit.com endpoint. It is intended for connecting to publicly available GopherPit service.

          func NewClientWithEndpoint

          func NewClientWithEndpoint(endpoint, key string) *Client

            NewClientWithEndpoint creates a new Client object with HTTP endpoint and Personal Access Token as a key. It is intended for connecting to on-premises GopherPit installations. Endpoint URL must include schema, host and path components. For example: https://go.example.com/api/v1

            func (Client) AddDomain

            func (c Client) AddDomain(o *DomainOptions) (d Domain, err error)

              AddDomain creates a new Domain.

              func (Client) AddPackage

              func (c Client) AddPackage(o *PackageOptions) (p Package, err error)

                AddPackage creates a new Package.

                func (Client) DeleteDomain

                func (c Client) DeleteDomain(ref string) (d Domain, err error)

                  DeleteDomain removes a Domain.

                  func (Client) DeletePackage

                  func (c Client) DeletePackage(id string) (p Package, err error)

                    DeletePackage removes a Package.

                    func (Client) Domain

                    func (c Client) Domain(ref string) (d Domain, err error)

                      Domain retrieves a Domain instance.

                      func (Client) DomainPackages

                      func (c Client) DomainPackages(domainRef, start string, limit int) (page PackagesPage, err error)

                        DomainPackages retrieves a paginated list of Packages under a domain. Values from the previous and next fields in returned page can be provided as startRef argument to get a previous or next page in the listing.

                        func (Client) DomainTokens

                        func (c Client) DomainTokens(fqdn string) (tokens DomainTokens, err error)

                          DomainTokens retrieves a list of validation tokens for domain.

                          func (Client) DomainUsers

                          func (c Client) DomainUsers(ref string) (users DomainUsers, err error)

                            DomainUsers retrieves a list of user IDs that have write access to domain packages and domain owner user ID.

                            func (Client) Domains

                            func (c Client) Domains(startRef string, limit int) (page DomainsPage, err error)

                              Domains retrieves a paginated list of Domains. Values from the previous and next fields in returned page can be provided as startRef argument to get a previous or next page in the listing.

                              func (Client) GrantDomainUser

                              func (c Client) GrantDomainUser(ref, user string) error

                                GrantDomainUser gives write access to domain packages for a user.

                                func (Client) Package

                                func (c Client) Package(id string) (p Package, err error)

                                  Package retrieves a Package instance.

                                  func (Client) RevokeDomainUser

                                  func (c Client) RevokeDomainUser(ref, user string) error

                                    RevokeDomainUser removes write access to domain packages for a user.

                                    func (Client) UpdateDomain

                                    func (c Client) UpdateDomain(ref string, o *DomainOptions) (d Domain, err error)

                                      UpdateDomain updates fields of an existing Domain.

                                      func (Client) UpdatePackage

                                      func (c Client) UpdatePackage(id string, o *PackageOptions) (p Package, err error)

                                        UpdatePackage updates fields of an existing Package.

                                        type Domain

                                        type Domain struct {
                                        	ID                string `json:"id"`
                                        	FQDN              string `json:"fqdn"`
                                        	OwnerUserID       string `json:"owner_user_id"`
                                        	CertificateIgnore bool   `json:"certificate_ignore,omitempty"`
                                        	Disabled          bool   `json:"disabled,omitempty"`
                                        }

                                          Domain holds information about GopherPit domain instance.

                                          type DomainOptions

                                          type DomainOptions struct {
                                          	FQDN              *string `json:"fqdn,omitempty"`
                                          	OwnerUserID       *string `json:"owner_user_id,omitempty"`
                                          	CertificateIgnore *bool   `json:"certificate_ignore,omitempty"`
                                          	Disabled          *bool   `json:"disabled,omitempty"`
                                          }

                                            DomainOptions defines Domain fields that can be changed.

                                            type DomainToken

                                            type DomainToken struct {
                                            	FQDN  string `json:"fqdn"`
                                            	Token string `json:"token"`
                                            }

                                              DomainToken holds information about validation token for a specific fully qualified domain name.

                                              type DomainTokens

                                              type DomainTokens struct {
                                              	Tokens []DomainToken `json:"tokens"`
                                              }

                                                DomainTokens is an API response with a list of domain tokens.

                                                type DomainUsers

                                                type DomainUsers struct {
                                                	OwnerUserID string   `json:"owner_user_id"`
                                                	UserIDs     []string `json:"user_ids,omitempty"`
                                                }

                                                  DomainUsers holds information with User IDs who have access to a Domain.

                                                  type DomainsPage

                                                  type DomainsPage struct {
                                                  	Domains  []Domain `json:"domains"`
                                                  	Count    int      `json:"count"`
                                                  	Previous string   `json:"previous,omitempty"`
                                                  	Next     string   `json:"next,omitempty"`
                                                  }

                                                    DomainsPage is a paginated list of Domain instances.

                                                    type Package

                                                    type Package struct {
                                                    	ID          string  `json:"id"`
                                                    	DomainID    string  `json:"domain_id"`
                                                    	FQDN        string  `json:"fqdn"`
                                                    	Path        string  `json:"path"`
                                                    	VCS         VCS     `json:"vcs"`
                                                    	RepoRoot    string  `json:"repo_root"`
                                                    	RefType     RefType `json:"ref_type,omitempty"`
                                                    	RefName     string  `json:"ref_name,omitempty"`
                                                    	GoSource    string  `json:"go_source,omitempty"`
                                                    	RedirectURL string  `json:"redirect_url,omitempty"`
                                                    	Disabled    bool    `json:"disabled,omitempty"`
                                                    }

                                                      Package holds data that represents Go package location and metadata for remote import path. https://golang.org/cmd/go/#hdr-Remote_import_paths

                                                      type PackageOptions

                                                      type PackageOptions struct {
                                                      	Domain      *string  `json:"domain,omitempty"`
                                                      	Path        *string  `json:"path,omitempty"`
                                                      	VCS         *VCS     `json:"vcs,omitempty"`
                                                      	RepoRoot    *string  `json:"repo_root,omitempty"`
                                                      	RefType     *RefType `json:"ref_type"`
                                                      	RefName     *string  `json:"ref_name"`
                                                      	GoSource    *string  `json:"go_source,omitempty"`
                                                      	RedirectURL *string  `json:"redirect_url,omitempty"`
                                                      	Disabled    *bool    `json:"disabled,omitempty"`
                                                      }

                                                        PackageOptions defines Package fields that can be changed.

                                                        type PackagesPage

                                                        type PackagesPage struct {
                                                        	Packages []Package `json:"packages"`
                                                        	Count    int       `json:"count"`
                                                        	Previous string    `json:"previous,omitempty"`
                                                        	Next     string    `json:"next,omitempty"`
                                                        }

                                                          PackagesPage is a paginated list of Package instances.

                                                          type RefType

                                                          type RefType string

                                                            RefType is a type that defines possbile reference type values for the Package.

                                                            var (
                                                            	RefTypeBranch RefType = "branch"
                                                            	RefTypeTag    RefType = "tag"
                                                            )

                                                              Possible reference types.

                                                              type VCS

                                                              type VCS string

                                                                VCS is a type that defines possible VCS values for the Package.

                                                                var (
                                                                	VCSGit        VCS = "git"
                                                                	VCSMercurial  VCS = "hg"
                                                                	VCSBazaar     VCS = "bzr"
                                                                	VCSSubversion VCS = "svn"
                                                                )

                                                                  Possible VCS values.