Back to godoc.org
gopherpit.com/gopherpit / api

package api

v0.5.3
Latest Go to latest
Published: Aug 27, 2017 | License: BSD-3-Clause | Module: gopherpit.com/gopherpit

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

const MaxLimit = 100

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

Variables

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.

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.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier