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).