ns1

README

NS1 Golang SDK

This project is in active development.

The golang client for the NS1 API: https://ns1.com/api/

The documentation can be found here: https://pkg.go.dev/gopkg.in/ns1/ns1-go.v2

Installing

$ go get gopkg.in/ns1/ns1-go.v2

Examples

See more

package main

import (
	"fmt"
	"log"
	"net/http"
	"os"
	"time"

	api "gopkg.in/ns1/ns1-go.v2/rest"
)

func main() {
	k := os.Getenv("NS1_APIKEY")
	if k == "" {
		fmt.Println("NS1_APIKEY environment variable is not set, giving up")
		os.Exit(1)
	}

	httpClient := &http.Client{Timeout: time.Second * 10}
	client := api.NewClient(httpClient, api.SetAPIKey(k))

	zones, _, err := client.Zones.List()
	if err != nil {
		log.Fatal(err)
	}

	for _, z := range zones {
		fmt.Println(z.Zone)
	}

}

DNS views and compatibility with pre-2.6.6 SDK versions

DNS views allow NS1 to serve one set of data to one group of clients (e.g. internal employees), and different results to other groups of clients (e.g. public internet). Multiple zones can now have the same fully-qualified domain name (FQDN), with propagation controlled via ACLs and the Views feature. For more information, please refer to this NS1 documentation page.

Users who do not need views can ignore this feature. Users who do use views must now use the user-supplied name field in the API to uniquely identify a zone. More than one zone can have the same FQDN, but their name fields must be unique.

For compatibility, the zone field is unchanged in existing functions. When name and FQDN differ, and you are calling a func that takes zone, you must add the name identifier as well. The zone's FQDN is only required during zone or record creation.

When using views, the NewNamedZone and NewNamedRecord funcs are provided to create zones and records. If not using views, you can continue using the older functions.

Contributing

Pull Requests and issues are welcome. See the NS1 Contribution Guidelines for more information.

Run tests:

make test

Local dev: use the go.mod replace directive or go work use in client code to point to the local checkout of this repository.

Consider running ./script/install-git-hooks to install local git hooks for this project.

LICENSE

Apache2 - see the included LICENSE file for more information

Documentation

Overview

Package ns1 is the NS1 golang SDK.

To understand the REST models and terminology, please visit the ns1 web page:

https://ns1.com/