| 1 |
# Enterprise Client [](https://godoc.org/github.com/influxdb/enterprise-client/v1) |
| 2 |
|
| 3 |
The `enterprise-client` package is used to speak with the Enterprise API in a simple and straight forward way. No muss, no fuss! |
| 4 |
|
| 5 |
## V1 |
| 6 |
|
| 7 |
### Installation |
| 8 |
|
| 9 |
```go |
| 10 |
$ go get github.com/influxdb/enterprise-client/v1 |
| 11 |
``` |
| 12 |
|
| 13 |
### An Important Developers Note |
| 14 |
|
| 15 |
When testing and developing your applications to work with Enterprise, please make sure to change the `client.URL` to be something other than it's default, which is production. Might I recommend the following: |
| 16 |
|
| 17 |
```go |
| 18 |
client.URL = "https://enterprise.staging.influxdata.com" |
| 19 |
``` |
| 20 |
|
| 21 |
More info can be found in the documentation [here](https://godoc.org/github.com/influxdb/enterprise-client/v1#pkg-variables). |
| 22 |
|
| 23 |
__NOTE__: Applications should make this URL configurable. |
| 24 |
|
| 25 |
## Registering a Customer |
| 26 |
|
| 27 |
Customer's need to register with Enterprise and will receive a token in return. This token should be saved and sent along on all subsequent requests, more on this in a minute. |
| 28 |
|
| 29 |
Before sending a customer to Enterprise to register you will need to generate a URL to give to that customer. |
| 30 |
|
| 31 |
```go |
| 32 |
c := client.New("") |
| 33 |
r := client.Registration{ |
| 34 |
ClusterID: "clus1", |
| 35 |
Product: "chronograf", |
| 36 |
RedirectURL: "http://example.com", |
| 37 |
} |
| 38 |
|
| 39 |
u, err := c.RegistrationURL(r) |
| 40 |
``` |
| 41 |
|
| 42 |
If a `RedirectURL` was specified then the customer will be redirected to that URL after successfully completing their registration. There will also be a `token` query parameter attached to the URL, please retrieve and store this token for future use! |
| 43 |
|
| 44 |
__NOTE__: If there is no token stored locally (it is up to each app to store this token), when the application starts up they user should be prompted to register with Enterprise. |
| 45 |
|
| 46 |
## Registering a Server |
| 47 |
|
| 48 |
When an app wakes up (influxdb, chronograf, etc…) it attempt to register itself with Enterprise: |
| 49 |
|
| 50 |
|
| 51 |
```go |
| 52 |
c := client.New("token-goes-here") |
| 53 |
|
| 54 |
s := client.Server{ |
| 55 |
ClusterID: "clus1", |
| 56 |
Host: "example.com", |
| 57 |
Product: "influxdb", |
| 58 |
Version: "1.0", |
| 59 |
ServerID: "serv1", |
| 60 |
} |
| 61 |
|
| 62 |
res, err := c.Save(s) |
| 63 |
``` |
| 64 |
|
| 65 |
This should happen every time the application starts. |
| 66 |
|
| 67 |
## Posting Product Stats: |
| 68 |
|
| 69 |
Ideally when posting product stats data to Enterprise you will pass the "token". If no token is set then the data will __NOT__ be associated with any organization. |
| 70 |
|
| 71 |
```go |
| 72 |
c := client.New("token-goes-here") |
| 73 |
|
| 74 |
st := client.Stats{ |
| 75 |
ClusterID: "clus1", |
| 76 |
ServerID: "serv1", |
| 77 |
Product: "influxdb", |
| 78 |
Data: []client.StatsData{ |
| 79 |
client.StatsData{ |
| 80 |
Name: "engine", |
| 81 |
Tags: client.Tags{ |
| 82 |
"path": "/home/philip/.influxdb/data/_internal/monitor/1", |
| 83 |
"version": "bz1", |
| 84 |
}, |
| 85 |
Values: client.Values{ |
| 86 |
"blks_write": 39, |
| 87 |
"blks_write_bytes": 2421, |
| 88 |
"blks_write_bytes_c": 2202, |
| 89 |
"points_write": 39, |
| 90 |
"points_write_dedupe": 39, |
| 91 |
}, |
| 92 |
}, |
| 93 |
}, |
| 94 |
} |
| 95 |
|
| 96 |
res, err := c.Save(st) |
| 97 |
``` |
| 98 |
|
| 99 |
## Posting Usage Stats: |
| 100 |
|
| 101 |
Usage stats are anonymous stats sent to Enterprise every 12 hours. |
| 102 |
|
| 103 |
```go |
| 104 |
c := client.New("token-goes-here") |
| 105 |
|
| 106 |
u := client.Usage{ |
| 107 |
Product: "influxdb", |
| 108 |
Data: []client.UsageData{ |
| 109 |
{ |
| 110 |
Tags: client.Tags{ |
| 111 |
"version": "0.9.5", |
| 112 |
"arch": "amd64", |
| 113 |
"os": "linux", |
| 114 |
}, |
| 115 |
Values: client.Values{ |
| 116 |
"cluster_id": "23423", |
| 117 |
"server_id": "1", |
| 118 |
"num_databases": 3, |
| 119 |
"num_measurements": 2342, |
| 120 |
"num_series": 87232, |
| 121 |
}, |
| 122 |
}, |
| 123 |
}, |
| 124 |
} |
| 125 |
|
| 126 |
res, err := c.Save(u) |
| 127 |
``` |
| 128 |
|
| 129 |
## API Errors |
| 130 |
|
| 131 |
As you probably know [Go doesn't return error codes for non-2xx HTTP requests](http://metabates.com/2015/10/15/handling-http-request-errors-in-go/), but thankfully the Enterprise Client does! |
| 132 |
|
| 133 |
The API will return one of two errors back to you if there are any problems: |
| 134 |
|
| 135 |
* `SimpleError` - This type of error is common for status codes such as `401`, `404`, and `500`. [https://godoc.org/github.com/influxdb/enterprise-client/v1#SimpleError](https://godoc.org/github.com/influxdb/enterprise-client/v1#SimpleError) |
| 136 |
* `ValidationErrors` - Type type of error is common for status codes such as `422` and will return specific errors related to the validity of the payload sent to the API. [https://godoc.org/github.com/influxdb/enterprise-client/v1#ValidationErrors](https://godoc.org/github.com/influxdb/enterprise-client/v1#ValidationErrors) |
| 137 |
|
| 138 |
It is recommended to check for these errors and handle them appropriately. |