Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/equinixmetal-archive/packngo
[Deprecated] A Golang client for the Equinix Metal API. (Packet is now Equinix Metal)
https://github.com/equinixmetal-archive/packngo
baremetal equinix equinix-metal equinix-metal-api go golang packet packet-api
Last synced: 2 months ago
JSON representation
[Deprecated] A Golang client for the Equinix Metal API. (Packet is now Equinix Metal)
- Host: GitHub
- URL: https://github.com/equinixmetal-archive/packngo
- Owner: equinixmetal-archive
- License: other
- Archived: true
- Created: 2015-03-14T20:00:22.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-06-04T18:13:51.000Z (4 months ago)
- Last Synced: 2024-07-28T18:59:47.956Z (2 months ago)
- Topics: baremetal, equinix, equinix-metal, equinix-metal-api, go, golang, packet, packet-api
- Language: Go
- Homepage: https://deploy.equinix.com/labs/equinix-sdk-go/
- Size: 814 KB
- Stars: 79
- Watchers: 32
- Forks: 60
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: code-of-conduct.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# packngo
[](https://github.com/equinix-labs/equinix-labs/blob/main/uniform-standards.md)
[](https://github.com/packethost/packngo/releases/latest)
[](https://godoc.org/github.com/packethost/packngo)
[](https://goreportcard.com/report/github.com/packethost/packngo)
[](https://slack.equinixmetal.com/)
[](https://twitter.com/intent/follow?screen_name=equinixmetal)
> **[Deprecated](https://github.com/equinix-labs/equinix-labs/blob/main/deprecated-statement.md)** This repository is Deprecated, meaning that this software is only supported or maintained by Equinix Metal and its community in a case-by-case basis. It has been replaced by [`equinix-sdk-go`](https://github.com/equinix/equinix-sdk-go), which is generated from Equinix OpenAPI specs and is intended to support Equinix services beyond only Metal.
A Golang client for the Equinix Metal API. ([Packet is now Equinix Metal](https://blog.equinix.com/blog/2020/10/06/equinix-metal-metal-and-more/))
## Installation
To import this library into your Go project:
```go
import "github.com/packethost/packngo"
```
**Note:** A minimum of Go 1.14 is required for development.
Download module with:
```sh
go get github.com/packethost/packngo
```
## Stability and Compatibility
This repository is [Maintained](https://github.com/equinix-labs/equinix-labs/blob/main/maintained-statement.md) meaning that this software is supported by Equinix Metal and its community - available to use in production environments.
Packngo is currently provided with a major version of [v0](https://blog.golang.org/v2-go-modules). We'll try to avoid breaking changes to this library, but they will certainly happen as we work towards a stable v1 library. See [CHANGELOG.md](CHANGELOG.md) for details on the latest additions, removals, fixes, and breaking changes.
While packngo provides an interface to most of the [Equinix Metal API](https://metal.equinix.com/developers/api/), the API is regularly adding new features. To request or contribute support for more API end-points or added fields, [create an issue](https://github.com/packethost/packngo/issues/new).
See [SUPPORT.md](SUPPORT.md) for any other issues.
## Usage
To authenticate to the Equinix Metal API, you must have your API token exported in env var `PACKET_AUTH_TOKEN`.
This code snippet initializes Equinix Metal API client, and lists your Projects:
```go
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 library is used by the official [terraform-provider-equinix](https://github.com/equinix/terraform-provider-equinix).
You can also learn a lot from the `*_test.go` sources. Almost all out tests touch the Equinix Metal API, so you can see how auth, querying and POSTing works. For example [devices_test.go](devices_test.go).
Linked Resources
### Linked resources in Get\* and List\* functions
The Equinix Metal API includes references to related entities for a wide selection of resource types, indicated by `href` fields. The Equinix Metal API allows for these entities to be included in the API response, saving the user from making more round-trip API requests. This is useful for linked resources, e.g members of a project, devices in a project. Similarly, by excluding entities that are included by default, you can reduce the API response time and payload size.
Control of this behavior is provided through [common attributes](https://metal.equinix.com/developers/api/common-parameters/) that can be used to toggle, by field name, which referenced resources will be included as values in API responses. The API exposes this feature through `?include=` and `?exclude=` query parameters which accept a comma-separated list of field names. These field names can be dotted to reference nested entities.
Most of the packngo `Get` functions take references to `GetOptions` parameters (or `ListOptions` for `List` functions). These types include an `Include` and `Exclude` slice that will be converted to query parameters upon request.
For example, if you want to list users in a project, you can fetch the project via `Projects.Get(pid, nil)` call. The result of this call will be a `Project` which has a `Users []User` attribute. The items in the `[]User` slice only have a non-zero URL attribute, the rest of the fields will be type defaults. You can then parse the ID of the User resources and fetch them consequently.
Optionally, you can use the ListOptions struct in the project fetch call to include the Users (`members` JSON tag). Then, every item in the `[]User` slice will have all (not only the `Href`) attributes populated.
```go
Projects.Get(pid, &packngo.ListOptions{Includes: []{'members'}})
```
The following is a more comprehensive illustration of Includes and Excludes.
```go
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)
}
```
### Deprecation and Sunset
If the Equinix Metal API returns a [RFC-8594](https://tools.ietf.org/html/rfc8594) `Deprecation` or `Sunset` header, packngo will log this header to stderr with any accompanied `Link` headers.
Example:
```console
WARNING: "POST /deprecate-and-sunset" reported deprecation
WARNING: "POST /deprecate-and-sunset" reported sunsetting on Sat, 1 Aug 2020 23:59:59 GMT
WARNING: See for deprecation details
WARNING: See for sunset details
WARNING: See for sunset details
WARNING: See for deprecation details
```
## Contributing
See [CONTIBUTING.md](CONTRIBUTING.md).