atlas

package module
v0.0.0-...-f006ba5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 28, 2015 License: MIT Imports: 9 Imported by: 0

README

Atlas API

GoDoc

This is the documentation and guide for the Atlas API. You can use it to create and update boxes, versions and providers.

import "github.com/larryli/atlas.v1"

api := atlas.New("--replace-your-access-token--")
box := api.Box("yourname", "boxname")
if box.New() == nil {
	version := box.Version(0)
	version.Version = "0.0.1"
	if version.New() == nil {
		provider := version.Provider(atlas.ProviderVirtualbox)
		provider.OriginalUrl = "http://your.box.url"
		if provider.New() == nil {
			version.Release()
		}
	}
}

Documentation

Overview

Atlas Api

This is the documentation and guide for the Atlas API. You can use it to create and update boxes, versions and providers. 

import "github.com/larryli/atlas.v1"

api := atlas.New("--replace-your-access-token--")
box := api.Box("yourname", "boxname")
if box.New() == nil {
	version := box.Version(0)
	version.Version = "0.0.1"
	if version.New() == nil {
		provider := version.Provider(atlas.ProviderVirtualbox)
		provider.OriginalUrl = "http://your.box.url"
		if provider.New() == nil {
			version.Release()
		}
	}
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewError 

func NewError(msg string, errs string) error

Types

type Api 

type Api struct {
	// contains filtered or unexported fields
}

func New 

func New(token string) *Api

All requests must be authenticated with an access_token and sent as a URL parameter. This token can be generated or revoked on the account tokens page. Your token will have access to all resources your account has access to.

func NewFromFile 

func NewFromFile(fname string) (*Api, error)

func (*Api) Box 

func (a *Api) Box(username, name string) *Box

func (*Api) Delete 

func (a *Api) Delete(uri string) ([]byte, error)

func (*Api) Download 

func (a *Api) Download(uri string, data io.Writer) error

func (*Api) Get 

func (a *Api) Get(uri string) ([]byte, error)

func (*Api) Post 

func (a *Api) Post(uri string, params url.Values) ([]byte, error)

func (*Api) Put 

func (a *Api) Put(uri string, params url.Values) ([]byte, error)

func (*Api) Upload 

func (a *Api) Upload(uri string, data io.Reader) ([]byte, error)

type Box 

type Box struct {
	CreatedAt           time.Time `json:"created_at"`
	UpdatedAt           time.Time `json:"updated_at"`
	Tag                 string    `json:"tag"`
	Name                string    `json:"name"`
	ShortDescription    string    `json:"short_description"`
	DescriptionHtml     string    `json:"description_html"`
	DescriptionMarkdown string    `json:"description_markdown"`
	Username            string    `json:"username"`
	Private             bool      `json:"private"`
	CurrentVersion      Version   `json:"current_version"`
	Versions            []Version `json:"versions"`
	// contains filtered or unexported fields
}

Boxes are the primary resource on Atlas. Before creating versions with attached providers, you'll need to create a box.

func (*Box) Delete 

func (b *Box) Delete() error

DESTROY A BOX 

Name (required)
	The name of the box, used to identify it.
	The name makes up the latter half of the tag.
	It has a maximum length of 36 characters and must contain only letters,
	numbers, dashes, underscores or periods.
Username (required)
	The username to assign the box to.
	You must be a member of the organization and have the ability to create boxes.
	Defaults to the users username that is making the API request.

func (*Box) Get 

func (b *Box) Get() error

RETRIEVE A BOX

func (*Box) New 

func (b *Box) New() error

CREATE A BOX 

Name (required)
	The name of the box, used to identify it.
	The name makes up the latter half of the tag.
	It has a maximum length of 36 characters and must contain only letters,
	numbers, dashes, underscores or periods.
Username
	The username to assign the box to.
	You must be a member of the organization and have the ability to create boxes.
	Defaults to the users username that is making the API request.
ShortDescription
	The short description is used on small box previews,
	in search results and other places where displaying markdown isn't functional.
	It has a maxium length of 120 characters.
DescriptionMarkdown
	Markdown text used as a full-length and in-depth description of the box.
	Markdown is parsed according to GitHub Flavored Markdown.
	There is no maximum length.
Private
	A boolean if the box should be private or not.

func (*Box) Set 

func (b *Box) Set() error

UPDATE A BOX 

Name (required)
	The name of the box, used to identify it.
	The name makes up the latter half of the tag.
	It has a maximum length of 36 characters and must contain only letters,
	numbers, dashes, underscores or periods.
Username (required)
	The username to assign the box to.
	You must be a member of the organization and have the ability to create boxes.
	Defaults to the users username that is making the API request.
ShortDescription
	The short description is used on small box previews,
	in search results and other places where displaying markdown isn't functional.
	It has a maxium length of 120 characters.
DescriptionMarkdown
	Markdown text used as a full-length and in-depth description of the box.
	Markdown is parsed according to GitHub Flavored Markdown.
	There is no maximum length.
Private
	A boolean if the box should be private or not.

func (*Box) Uri 

func (b *Box) Uri() string

func (*Box) Version 

func (b *Box) Version(number string) *Version

type Error 

type Error struct {
	Msg    string
	Errors interface{}
}

Standard HTTP response codes are returned. 404 Not Found codes are returned for all resources that a user does not have access to, as well as for resources that don't exist. This is done to avoid a potential attacker discovery the existence of a resource.

Errors format: 

{
	"name": [
		"has already been taken"
	]
}

func (*Error) Error 

func (e *Error) Error() string

type Provider 

type Provider struct {
	Name        ProviderName `json:"name"`
	Hosted      bool         `json:"hosted"`
	HostedToken string       `json:"hosted_token"`
	OriginalUrl string       `json:"original_url"`
	UploadUrl   string       `json:"upload_url"`
	CreatedAt   time.Time    `json:"created_at"`
	UpdatedAt   time.Time    `json:"updated_at"`
	DownloadUrl string       `json:"download_url"`
	// contains filtered or unexported fields
}

Providers contain the pointers to the box files, be it a hosted or self-hosted box. Versions can have many providers, each which represents a Vagrant compatible provider, either from Vagrant Core as a 3rd party plugin.

func (*Provider) Delete 

func (p *Provider) Delete() error

DESTROY A PROVIDER 

Name (required)
	The name of the provider. Vagrant will use this to determine compatible boxes on the client.
	Common providers include virtualbox, vmware_desktop, digitalocean, aws, rackspace, and hyperv.

func (*Provider) Download 

func (p *Provider) Download(data io.Writer) error

DOWNLOAD A .BOX FOR PROVIDER 

Name (required)
	The name of the provider. Vagrant will use this to determine compatible boxes on the client.
	Common providers include virtualbox, vmware_desktop, digitalocean, aws, rackspace, and hyperv.

func (*Provider) Get 

func (p *Provider) Get() error

RETRIEVE A PROVIDER 

Name (required)
	The name of the provider. Vagrant will use this to determine compatible boxes on the client.
	Common providers include virtualbox, vmware_desktop, digitalocean, aws, rackspace, and hyperv.

func (*Provider) New 

func (p *Provider) New() error

CREATE A PROVIDER 

Name (required)
	The name of the provider. Vagrant will use this to determine compatible boxes on the client.
	Common providers include virtualbox, vmware_desktop, digitalocean, aws, rackspace, and hyperv.
OriginalUrl
	An HTTP URL to the box file.
	This must be accessible at this URL from the machine where you expect a user to download the box by using Vagrant.
	If ommitted, we assume you wish to host the provider with Atlas.

The provider API is used to host boxes. To create a hosted box, simply omit the URL parameter. You will then be able to use the upload endpoint to upload a box to us.

func (*Provider) Set 

func (p *Provider) Set() error

UPDATE A PROVIDER 

Name (required)
	The name of the provider. Vagrant will use this to determine compatible boxes on the client.
	Common providers include virtualbox, vmware_desktop, digitalocean, aws, rackspace, and hyperv.
OriginalUrl
	An HTTP URL to the box file.
	This must be accessible at this URL from the machine where you expect a user to download the box by using Vagrant.
	If ommitted, we assume you wish to host the provider with Atlas.

func (*Provider) Upload 

func (p *Provider) Upload(data io.Reader) error

UPLOAD A .BOX FOR PROVIDER 

	Name (required)
		The name of the provider. Vagrant will use this to determine compatible boxes on the client.
		Common providers include virtualbox, vmware_desktop, digitalocean, aws, rackspace, and hyperv.
 data (io.Reader, required)

The upload path returns a URL that you can then PUT the boxes payload to. After streaming the box, you can confirm the upload by comparing the token provided in the UPLOAD response with the token returned from the providers GET route. When these tokens match, the upload has been successful.

func (*Provider) Uri 

func (p *Provider) Uri() string

type ProviderName 

type ProviderName string
const (
	ProviderVirtualbox    ProviderName = "virtualbox"
	ProviderVmwareDesktop ProviderName = "vmware_desktop"
	ProviderDigitalocean  ProviderName = "digitalocean"
	ProviderAws           ProviderName = "aws"
	ProviderRackspace     ProviderName = "rackspace"
	ProviderHyperv        ProviderName = "hyperv"
)

type Version 

type Version struct {
	Version             string        `json:"version"`
	Status              VersionStatus `json:"status"`
	DescriptionHtml     string        `json:"description_html"`
	DescriptionMarkdown string        `json:"description_markdown"`
	CreatedAt           time.Time     `json:"created_at"`
	UpdatedAt           time.Time     `json:"updated_at"`
	Number              string        `json:"number"`
	Downloads           int           `json:"downloads"`
	ReleaseUrl          string        `json:"release_url"`
	RevokeUrl           string        `json:"revoke_url"`
	Providers           []Provider    `json:"providers"`
	// contains filtered or unexported fields
}

Versions represent new releases for boxes, and contain both information about the changes in that version as well as being the parent object for providers, which contain the eventual box file.

func (*Version) Delete 

func (v *Version) Delete() error

DESTROY A VERSION 

Version (required)
	The version number, typically incrementing a previous version.
	We validate this version string based on Semantic Versioning.
	We only require that the string matches a pattern that could be semver,
	and don't validate that the version comes after your previous versions, and so on.

func (*Version) Get 

func (v *Version) Get() error

RETRIEVE A VERSION 

Version (required)
	The version number, typically incrementing a previous version.
	We validate this version string based on Semantic Versioning.
	We only require that the string matches a pattern that could be semver,
	and don't validate that the version comes after your previous versions, and so on.

func (*Version) New 

func (v *Version) New() error

CREATE A VERSION 

Version (required)
	The version number, typically incrementing a previous version.
	We validate this version string based on Semantic Versioning.
	We only require that the string matches a pattern that could be semver,
	and don't validate that the version comes after your previous versions, and so on.
DescriptionMarkdown
	Markdown text used as a full-length and in-depth description of the version,
	typically for denoting changes introduced. Markdown is parsed according to GitHub Flavored Markdown.
	There is no maximum length.

When a version is first created, its status is set to unreleased.

func (*Version) Provider 

func (v *Version) Provider(name ProviderName) *Provider

func (*Version) Release 

func (v *Version) Release() error

RELEASE A VERSION 

Version (required)
	The version number, typically incrementing a previous version.
	We validate this version string based on Semantic Versioning.
	We only require that the string matches a pattern that could be semver,
	and don't validate that the version comes after your previous versions, and so on.

This allows you to update the providers and description prior to release. Once a version is ready to release, you can then make a request to move it to an active state.

func (*Version) Revoke 

func (v *Version) Revoke() error

REVOKE A VERSION 

Version (required)
	The version number, typically incrementing a previous version.
	We validate this version string based on Semantic Versioning.
	We only require that the string matches a pattern that could be semver,
	and don't validate that the version comes after your previous versions, and so on.

Versions that have been "released" can then no longer be deleted. Instead, you should "revoke" a released version, setting the status as revoked. This stops access to the version from Vagrant, but maintains the history of the version.

func (*Version) Set 

func (v *Version) Set() error

UPDATE A VERSION 

Version (required)
	The version number, typically incrementing a previous version.
	We validate this version string based on Semantic Versioning.
	We only require that the string matches a pattern that could be semver,
	and don't validate that the version comes after your previous versions, and so on.
DescriptionMarkdown
	Markdown text used as a full-length and in-depth description of the version,
	typically for denoting changes introduced. Markdown is parsed according to GitHub Flavored Markdown.
	There is no maximum length.

You cannot modify the status attribute directly, so their are seperate endpoints to revoke and release versions.

func (*Version) Uri 

func (v *Version) Uri() string

type VersionStatus 

type VersionStatus string
const (
	VersionUnreleased VersionStatus = "unreleased"
	VersionActive     VersionStatus = "active"
	VersionRevoked    VersionStatus = "revoked"
)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.