Packet Go API Client
Clone or download
Latest commit dbd3c07 Dec 13, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Instance batches Sep 26, 2018
metadata Instance batches Sep 26, 2018
.drone.yml update drone test container to go 1.9 May 9, 2018
.gitignore Pagination for organizations Nov 20, 2018
CHANGELOG.md mention org support in Changelog Feb 7, 2018
LICENSE.txt first! Mar 14, 2015
README.md Explain linked resoruces, Includes and Excludes in the README Dec 6, 2018
batches.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
batches_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
bgp_configs.go Fix BGP sessions param in BGP config Nov 27, 2018
bgp_configs_test.go Fix BGP sessions param in BGP config Nov 27, 2018
bgp_sessions.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
bgp_sessions_test.go Fix BGP sessions param in BGP config Nov 27, 2018
billing_address.go Added billing address and payment method Feb 7, 2018
capacities.go Added return object to Check function Sep 26, 2018
capacities_test.go fixed error check Sep 27, 2018
devices.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
devices_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
email.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
email_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
events.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
events_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
facilities.go clean facilities service and test Dec 13, 2018
facilities_test.go clean facilities service and test Dec 13, 2018
hardware_reservations.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
hardware_reservations_test.go Instance batches Sep 26, 2018
ip.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
ip_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
notifications.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
notifications_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
operatingsystems.go Instance batches Sep 26, 2018
operatingsystems_test.go Instance batches Sep 26, 2018
organizations.go go vet fixes Nov 27, 2018
organizations_test.go Pagination for organizations Nov 20, 2018
packngo.go change varname from l to g in GetOptions functions Nov 21, 2018
packngo_test.go Pagination for organizations Nov 20, 2018
payment_methods.go go vet fixes Nov 27, 2018
plans.go make AvailableIn []Facility, write simple test Dec 5, 2018
plans_test.go fix plan test check Dec 6, 2018
ports.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
ports_test.go Facility string -> Facility []string Oct 4, 2018
projects.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
projects_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
rate.go Ran gofmt against all files. Jul 21, 2016
spotmarket.go refactor NewRequest/Do pattern to just DoRequest Oct 19, 2017
spotmarket_test.go Instance batches Sep 26, 2018
spotmarketrequest.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
spotmarketrequest_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
sshkeys.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
sshkeys_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
timestamp.go first! Mar 14, 2015
two_factor_auth.go Instance batches Sep 26, 2018
user.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
user_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
utils.go Add listing of device plans Dec 13, 2018
virtualnetworks.go fixes in VLAN handling Nov 22, 2018
virtualnetworks_test.go fixes in VLAN handling Nov 22, 2018
volumes.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
volumes_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
vpn.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018
vpn_test.go Implement Include and Exclude in most of Get and List methods Nov 19, 2018

README.md

packngo

Packet Go Api Client

Installation

go get github.com/packethost/packngo

Usage

To authenticate to the Packet API, you must have your API token exported in env var PACKET_AUTH_TOKEN.

This code snippet initializes Packet API client, and lists your Projects:

package main

import (
	"log"

	"github.com/packethost/packngo"
)

func main() {
	c, err := packngo.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	ps, _, err := c.Projects.List(nil)
	if err != nil {
		log.Fatal(err)
	}
	for _, p := range ps {
		log.Println(p.ID, p.Name)
	}
}

This lib is used by the official terraform-provider-packet.

You can also learn a lot from the *_test.go sources. Almost all out tests touch the Packet API, so you can see how auth, querying and POSTing works. For example devices_test.go.

Linked resources in Get* and List* functions

Most of the Get and List functions have *GetOptions resp. *ListOptions paramters. If you supply them, you can specify which attributes of resources in the return set can be excluded or included. This is useful for linked resources, e.g members of a project, devices in a project.

Linked resources usually have only the Href attribute populated, allowing you to fetch them in another API call. But if you explicitly include the linked resoruce attribute, it will be populated in the result set of the linking resource.

For example, if you want to list users in a project, you can fetch the project via Projects.Get(pid, nil) call. Result from the call will be a Project struct which has Users []User attribute. The items in the []User slice only have the URL attribute non-zero, the rest of the fields will be type defaults. You can then parse the ID of the User resources and fetch them consequently. Or, you can use the ListOptions struct in the project fetch call to include the Users (members JSON tag) as

Projects.Get(pid, &packngo.ListOptions{Includes: []{'members'}})` 

Then, every item in the []User slice will have all (not only the URL) attributes populated. Following code illustrates the Includes and Excludes.

import (
	"log"

	"github.com/packethost/packngo"
)

func listProjectsAndUsers(lo *packngo.ListOptions) {
	c, err := packngo.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	ps, _, err := c.Projects.List(lo)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Listing for listOptions %+v\n", lo)
	for _, p := range ps {
		log.Printf("project resource %s has %d users", p.Name, len(p.Users))
		for _, u := range p.Users {
			if u.Email != "" && u.FullName != "" {
				log.Printf("  user %s has email %s\n", u.FullName, u.Email)
			} else {
				log.Printf("  only got user link %s\n", u.URL)
			}
		}
	}
}

func main() {
	loMembers := &packngo.ListOptions{Includes: []string{"members"}}
	loMembersOut := &packngo.ListOptions{Excludes: []string{"members"}}
	listProjectsAndUsers(loMembers)
	listProjectsAndUsers(nil)
	listProjectsAndUsers(loMembersOut)
}

Acceptance Tests

If you want to run tests against the actual Packet API, you must set envvar PACKET_TEST_ACTUAL_API to non-empty string for the go test. The device tests wait for the device creation, so it's best to run a few in parallel.

To run a particular test, you can do

$ PACKNGO_TEST_ACTUAL_API=1 go test -v -run=TestAccDeviceBasic

If you want to see HTTP requests, set the PACKNGO_DEBUG env var to non-empty string, for example:

$ PACKNGO_DEBUG=1 PACKNGO_TEST_ACTUAL_API=1 go test -v -run=TestAccVolumeUpdate

Committing

Before committing, it's a good idea to run gofmt -w *.go. (gofmt)