You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is an SDK for interfacing with UpCloud's API using the Go programming language. It is loosely based on similar
8
-
SDKs such as https://github.com/aws/aws-sdk-go.
7
+
This is the SDK for interfacing with UpCloud's API using the Go programming language. The features in the development kit allow easy application creation and simplify UpCloud API integration when using Go.
9
8
10
9
## Installation and requirements
11
10
12
-
You'll need Go 1.6 or higher to use the SDK. You can use the following command to retrieve the SDK:
11
+
You'll need Go 1.7 or higher to use the SDK. You can use the following command to retrieve the SDK:
13
12
14
13
```
15
-
go get github.com/Jalle19/upcloud-go-sdk
14
+
go get github.com/UpCloudLtd/upcloud-go-sdk
16
15
```
17
16
18
17
## Usage
19
18
20
-
The general pattern for using the SDK goes like this:
19
+
The general usage of the SDK adheres to the following pattern:
21
20
22
-
* Create a `client.Client`
23
-
* Create a `service.Service` by passing the newly created client object to it
24
-
* Interface with the API using the various methods of the service object. Methods that take parameters wrap them in
25
-
request objects.
21
+
* Authenticate by creating a `client.Client`
22
+
* Create a `service.Service` by passing the newly created `client` object to it
23
+
* Interface with the API using the various methods of the `service` object. Methods that take parameters wrap them in request objects.
26
24
27
-
The examples here only deal with how to use the SDK itself. For information on how to use the API in general, please
28
-
consult the [official documentation](https://www.upcloud.com/api/).
25
+
We recommend setting up a separate subaccount for API usage to allow better access control and security. You can find out more about creating subaccounts at the following support article for [Server Tags and Group Accounts](https://www.upcloud.com/support/server-tags-and-group-accounts/). We strongly recommend limiting the connections to a specific address or address range for security purposes.
26
+
27
+
The examples here only deal with how to use the SDK itself. For information on how to use the API in general, please consult the [UpCloud API documentation](https://www.upcloud.com/api/).
29
28
30
29
### Creating the client and the service
31
30
32
31
```go
33
-
//Upcloud doesn't use dedicated API keys, instead you pass your account login credentials to the client
32
+
//Authenticate by passing your account login credentials to the client
34
33
c:= client.New(user, password)
35
34
36
35
// It is generally a good idea to override the default timeout of the underlying HTTP client since some requests block for longer periods of time
@@ -42,8 +41,7 @@ svc := service.New(c)
42
41
43
42
### Validating credentials
44
43
45
-
The easiest way to check whether the client credentials are correct is to issue a call to `GetAccount()` (since it
46
-
doesn't require any parameters).
44
+
The easiest way to check whether the client credentials are correct is to issue a call to `GetAccount()`.
47
45
48
46
```go
49
47
username:="completely"
@@ -60,9 +58,7 @@ if err != nil {
60
58
61
59
### Error handling
62
60
63
-
All `Service` methods return a result and an error object. You can differentiate between generic connection errors
64
-
(like the API not being reachable) and service errors, which are errors returned in the response body by the API. This
65
-
is useful if you want to gracefully recover from certain types of errors.
61
+
All `Service` methods return a result and an error object. You can differentiate between generic connection errors (like the API not being reachable) and service errors, which are errors returned in the response body by the API. This is useful for gracefully recovering from certain types of errors.
66
62
67
63
```go
68
64
username:="completely"
@@ -93,6 +89,8 @@ The rest of these examples assume you already have a service object configured a
93
89
94
90
### Retrieving a list of servers
95
91
92
+
The following example will retrieve a list of servers the account has access to.
93
+
96
94
```go
97
95
// Retrieve the list of servers
98
96
servers, err := svc.GetServers()
@@ -109,8 +107,10 @@ for _, server := range servers.Servers {
109
107
110
108
### Creating a new server
111
109
110
+
Since the request for creating a new server is asynchronous, the server will report its status as "maintenance" until the deployment has been fully completed.
111
+
112
112
```go
113
-
// Create the server. The state will be "maintenance" since the request is asynchronous
@@ -163,8 +163,7 @@ fmt.Println("Server is now started")
163
163
164
164
### Templatizing a server's storage device
165
165
166
-
In this example we assume that there is a server represented by the variable `serverDetails` and that the server state
167
-
is `stopped`. We also assume that we want to templatize the first storage device of the server only.
166
+
In this example, we assume that there is a server represented by the variable `serverDetails` and that the server state is `stopped`. The next piece of code allows you to templatize the first storage device of the server.
168
167
169
168
```go
170
169
// Loop through the storage devices
@@ -189,8 +188,7 @@ for i, storage := range serverDetails.StorageDevices {
189
188
190
189
### Create a manual backup
191
190
192
-
In this example, we assume that there is a storage device represented by `storageDetails` and that if it is attached
193
-
to any server, the server is stopped.
191
+
In this example, we assume that there is a storage device represented by `storageDetails` and that if it is attached to any server, the server is stopped.
0 commit comments