github.com/civo/civogo@v0.3.65/README.md (about) 1 # Civogo - The Golang client library for Civo 2 3 [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/civo/civogo?tab=doc) 4 [![Build Status](https://github.com/civo/civogo/workflows/Test/badge.svg)](https://github.com/civo/civogo/actions) 5 [![Lint](https://github.com/civo/civogo/workflows/Lint/badge.svg)](https://github.com/civo/civogo/actions) 6 7 Civogo is a Go client library for accessing the Civo cloud API. 8 9 You can view the client API docs at [https://pkg.go.dev/github.com/civo/civogo](https://pkg.go.dev/github.com/civo/civogo) and view the API documentation at [https://api.civo.com](https://api.civo.com) 10 11 12 ## Install 13 14 ```sh 15 go get github.com/civo/civogo 16 ``` 17 18 ## Usage 19 20 ```go 21 import "github.com/civo/civogo" 22 ``` 23 24 From there you create a Civo client specifying your API key and a region. Then you can use public methods to interact with Civo's API. 25 26 ### Authentication 27 28 You will need both an API key and a region code to create a new client. 29 30 Your API key is listed within the [Civo control panel's security page](https://www.civo.com/account/security). You can also reset the token there, for example, if accidentally put it in source code and found it had been leaked. 31 32 For the region code, use any region you know exists, e.g. `LON1`. See the [API documentation](https://github.com/civo/civogo.git) for details. 33 34 ```go 35 package main 36 37 import ( 38 "context" 39 "github.com/civo/civogo" 40 ) 41 42 const ( 43 apiKey = "mykeygoeshere" 44 regionCode = "LON1" 45 ) 46 47 func main() { 48 client, err := civogo.NewClient(apiKey, regionCode) 49 // ... 50 } 51 ``` 52 53 ## Examples 54 55 To create a new Instance: 56 57 ```go 58 config, err := client.NewInstanceConfig() 59 if err != nil { 60 t.Errorf("Failed to create a new config: %s", err) 61 return err 62 } 63 64 config.Hostname = "foo.example.com" 65 66 instance, err := client.CreateInstance(config) 67 if err != nil { 68 t.Errorf("Failed to create instance: %s", err) 69 return err 70 } 71 ``` 72 73 To get all Instances: 74 75 ```go 76 instances, err := client.ListAllInstances() 77 if err != nil { 78 t.Errorf("Failed to create instance: %s", err) 79 return err 80 } 81 82 for _, i := range instances { 83 fmt.Println(i.Hostname) 84 } 85 ``` 86 87 ### Pagination 88 89 If a list of objects is paginated by the API, you must request pages individually. For example, to fetch all instances without using the `ListAllInstances` method: 90 91 ```go 92 func MyListAllInstances(client *civogo.Client) ([]civogo.Instance, error) { 93 list := []civogo.Instance{} 94 95 pageOfItems, err := client.ListInstances(1, 50) 96 if err != nil { 97 return []civogo.Instance{}, err 98 } 99 100 if pageOfItems.Pages == 1 { 101 return pageOfItems.Items, nil 102 } 103 104 for page := 2; page<=pageOfItems.Pages; page++ { 105 pageOfItems, err := client.ListInstances(1, 50) 106 if err != nil { 107 return []civogo.Instance{}, err 108 } 109 110 list = append(list, pageOfItems.Items) 111 } 112 113 return list, nil 114 } 115 ``` 116 117 ## Error handler 118 119 In the latest version of the library we have added a new way to handle errors. 120 Below are some examples of how to use the new error handler, and the complete list of errors is [here](errors.go). 121 122 This is an example of how to make use of the new errors, suppose we want to create a new Kubernetes cluster, and do it this way but choose a name that already exists within the clusters that we have: 123 124 ```go 125 // kubernetes config 126 configK8s := &civogo.KubernetesClusterConfig{ 127 NumTargetNodes: 5, 128 Name: "existent-name", 129 } 130 // Send to create the cluster 131 resp, err := client.NewKubernetesClusters(configK8s) 132 if err != nil { 133 if errors.Is(err, civogo.DatabaseKubernetesClusterDuplicateError) { 134 // add some actions 135 } 136 } 137 ``` 138 The following lines are new: 139 140 ```go 141 if err != nil { 142 if errors.Is(err, civogo.DatabaseKubernetesClusterDuplicateError) { 143 // add some actions 144 } 145 } 146 ``` 147 In this way. we can make decisions faster based on known errors, and we know what to expect. There is also the option of being able to say this to account for some errors but not others: 148 149 ```go 150 if err != nil { 151 if errors.Is(err, civogo.DatabaseKubernetesClusterDuplicateError) { 152 // add some actions 153 } 154 if errors.Is(err, civogo.UnknownError) { 155 // exit with error 156 } 157 } 158 ``` 159 We can use `UnknownError` for errors that are not defined. 160 161 ## Contributing 162 163 If you want to get involved, we'd love to receive a pull request - or an offer to help over our KUBE100 Slack channel. Please see the [contribution guidelines](CONTRIBUTING.md).